| <!doctype html> |
| <html> |
| <title>npm-coding-style</title> |
| <meta http-equiv="content-type" value="text/html;utf-8"> |
| <link rel="stylesheet" type="text/css" href="../../static/style.css"> |
| |
| <body> |
| <div id="wrapper"> |
| <h1><a href="../misc/npm-coding-style.html">npm-coding-style</a></h1> <p>npm's "funny" coding style</p> |
| |
| <h2 id="DESCRIPTION">DESCRIPTION</h2> |
| |
| <p>npm's coding style is a bit unconventional. It is not different for |
| difference's sake, but rather a carefully crafted style that is |
| designed to reduce visual clutter and make bugs more apparent.</p> |
| |
| <p>If you want to contribute to npm (which is very encouraged), you should |
| make your code conform to npm's style.</p> |
| |
| <p>Note: this concerns npm's code not the specific packages at npmjs.org</p> |
| |
| <h2 id="Line-Length">Line Length</h2> |
| |
| <p>Keep lines shorter than 80 characters. It's better for lines to be |
| too short than to be too long. Break up long lists, objects, and other |
| statements onto multiple lines.</p> |
| |
| <h2 id="Indentation">Indentation</h2> |
| |
| <p>Two-spaces. Tabs are better, but they look like hell in web browsers |
| (and on github), and node uses 2 spaces, so that's that.</p> |
| |
| <p>Configure your editor appropriately.</p> |
| |
| <h2 id="Curly-braces">Curly braces</h2> |
| |
| <p>Curly braces belong on the same line as the thing that necessitates them.</p> |
| |
| <p>Bad:</p> |
| |
| <pre><code>function () |
| {</code></pre> |
| |
| <p>Good:</p> |
| |
| <pre><code>function () {</code></pre> |
| |
| <p>If a block needs to wrap to the next line, use a curly brace. Don't |
| use it if it doesn't.</p> |
| |
| <p>Bad:</p> |
| |
| <pre><code>if (foo) { bar() } |
| while (foo) |
| bar()</code></pre> |
| |
| <p>Good:</p> |
| |
| <pre><code>if (foo) bar() |
| while (foo) { |
| bar() |
| }</code></pre> |
| |
| <h2 id="Semicolons">Semicolons</h2> |
| |
| <p>Don't use them except in four situations:</p> |
| |
| <ul><li><code>for (;;)</code> loops. They're actually required.</li><li>null loops like: <code>while (something) ;</code> (But you'd better have a good |
| reason for doing that.)</li><li><code>case "foo": doSomething(); break</code></li><li>In front of a leading <code>(</code> or <code>[</code> at the start of the line. |
| This prevents the expression from being interpreted |
| as a function call or property access, respectively.</li></ul> |
| |
| <p>Some examples of good semicolon usage:</p> |
| |
| <pre><code>;(x || y).doSomething() |
| ;[a, b, c].forEach(doSomething) |
| for (var i = 0; i < 10; i ++) { |
| switch (state) { |
| case "begin": start(); continue |
| case "end": finish(); break |
| default: throw new Error("unknown state") |
| } |
| end() |
| }</code></pre> |
| |
| <p>Note that starting lines with <code>-</code> and <code>+</code> also should be prefixed |
| with a semicolon, but this is much less common.</p> |
| |
| <h2 id="Comma-First">Comma First</h2> |
| |
| <p>If there is a list of things separated by commas, and it wraps |
| across multiple lines, put the comma at the start of the next |
| line, directly below the token that starts the list. Put the |
| final token in the list on a line by itself. For example:</p> |
| |
| <pre><code>var magicWords = [ "abracadabra" |
| , "gesundheit" |
| , "ventrilo" |
| ] |
| , spells = { "fireball" : function () { setOnFire() } |
| , "water" : function () { putOut() } |
| } |
| , a = 1 |
| , b = "abc" |
| , etc |
| , somethingElse</code></pre> |
| |
| <h2 id="Whitespace">Whitespace</h2> |
| |
| <p>Put a single space in front of ( for anything other than a function call. |
| Also use a single space wherever it makes things more readable.</p> |
| |
| <p>Don't leave trailing whitespace at the end of lines. Don't indent empty |
| lines. Don't use more spaces than are helpful.</p> |
| |
| <h2 id="Functions">Functions</h2> |
| |
| <p>Use named functions. They make stack traces a lot easier to read.</p> |
| |
| <h2 id="Callbacks-Sync-async-Style">Callbacks, Sync/async Style</h2> |
| |
| <p>Use the asynchronous/non-blocking versions of things as much as possible. |
| It might make more sense for npm to use the synchronous fs APIs, but this |
| way, the fs and http and child process stuff all uses the same callback-passing |
| methodology.</p> |
| |
| <p>The callback should always be the last argument in the list. Its first |
| argument is the Error or null.</p> |
| |
| <p>Be very careful never to ever ever throw anything. It's worse than useless. |
| Just send the error message back as the first argument to the callback.</p> |
| |
| <h2 id="Errors">Errors</h2> |
| |
| <p>Always create a new Error object with your message. Don't just return a |
| string message to the callback. Stack traces are handy.</p> |
| |
| <h2 id="Logging">Logging</h2> |
| |
| <p>Logging is done using the <a href="https://github.com/isaacs/npmlog">npmlog</a> |
| utility.</p> |
| |
| <p>Please clean up logs when they are no longer helpful. In particular, |
| logging the same object over and over again is not helpful. Logs should |
| report what's happening so that it's easier to track down where a fault |
| occurs.</p> |
| |
| <p>Use appropriate log levels. See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> and search for |
| "loglevel".</p> |
| |
| <h2 id="Case-naming-etc">Case, naming, etc.</h2> |
| |
| <p>Use <code>lowerCamelCase</code> for multiword identifiers when they refer to objects, |
| functions, methods, members, or anything not specified in this section.</p> |
| |
| <p>Use <code>UpperCamelCase</code> for class names (things that you'd pass to "new").</p> |
| |
| <p>Use <code>all-lower-hyphen-css-case</code> for multiword filenames and config keys.</p> |
| |
| <p>Use named functions. They make stack traces easier to follow.</p> |
| |
| <p>Use <code>CAPS_SNAKE_CASE</code> for constants, things that should never change |
| and are rarely used.</p> |
| |
| <p>Use a single uppercase letter for function names where the function |
| would normally be anonymous, but needs to call itself recursively. It |
| makes it clear that it's a "throwaway" function.</p> |
| |
| <h2 id="null-undefined-false-0">null, undefined, false, 0</h2> |
| |
| <p>Boolean variables and functions should always be either <code>true</code> or |
| <code>false</code>. Don't set it to 0 unless it's supposed to be a number.</p> |
| |
| <p>When something is intentionally missing or removed, set it to <code>null</code>.</p> |
| |
| <p>Don't set things to <code>undefined</code>. Reserve that value to mean "not yet |
| set to anything."</p> |
| |
| <p>Boolean objects are verboten.</p> |
| |
| <h2 id="SEE-ALSO">SEE ALSO</h2> |
| |
| <ul><li><a href="../misc/npm-developers.html">npm-developers(7)</a></li><li><a href="../misc/npm-faq.html">npm-faq(7)</a></li><li><a href="../cli/npm.html">npm(1)</a></li></ul> |
| </div> |
| <p id="footer">npm-coding-style — npm@1.3.21</p> |
| <script> |
| ;(function () { |
| var wrapper = document.getElementById("wrapper") |
| var els = Array.prototype.slice.call(wrapper.getElementsByTagName("*"), 0) |
| .filter(function (el) { |
| return el.parentNode === wrapper |
| && el.tagName.match(/H[1-6]/) |
| && el.id |
| }) |
| var l = 2 |
| , toc = document.createElement("ul") |
| toc.innerHTML = els.map(function (el) { |
| var i = el.tagName.charAt(1) |
| , out = "" |
| while (i > l) { |
| out += "<ul>" |
| l ++ |
| } |
| while (i < l) { |
| out += "</ul>" |
| l -- |
| } |
| out += "<li><a href='#" + el.id + "'>" + |
| ( el.innerText || el.text || el.innerHTML) |
| + "</a>" |
| return out |
| }).join("\n") |
| toc.id = "toc" |
| document.body.appendChild(toc) |
| })() |
| </script> |