mirror of https://github.com/lukechilds/node.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
216 lines
7.2 KiB
216 lines
7.2 KiB
<!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.20</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>
|
|
|