diff options
Diffstat (limited to 'deps/npm/html/doc/misc/npm-coding-style.html')
| -rw-r--r-- | deps/npm/html/doc/misc/npm-coding-style.html | 216 |
1 files changed, 216 insertions, 0 deletions
diff --git a/deps/npm/html/doc/misc/npm-coding-style.html b/deps/npm/html/doc/misc/npm-coding-style.html new file mode 100644 index 0000000000..a44f1dead2 --- /dev/null +++ b/deps/npm/html/doc/misc/npm-coding-style.html @@ -0,0 +1,216 @@ +<!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.3</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> |