diff options
Diffstat (limited to 'doc/misc/npm-coding-style.md')
-rw-r--r-- | doc/misc/npm-coding-style.md | 192 |
1 files changed, 0 insertions, 192 deletions
diff --git a/doc/misc/npm-coding-style.md b/doc/misc/npm-coding-style.md deleted file mode 100644 index 1199f63fc..000000000 --- a/doc/misc/npm-coding-style.md +++ /dev/null @@ -1,192 +0,0 @@ -npm-coding-style(7) -- npm's "funny" coding style -================================================= - -## DESCRIPTION - -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. - -If you want to contribute to npm (which is very encouraged), you should -make your code conform to npm's style. - -Note: this concerns npm's code not the specific packages that you can download from the npm registry. - -## Line Length - -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. - -## Indentation - -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. - -Configure your editor appropriately. - -## Curly braces - -Curly braces belong on the same line as the thing that necessitates them. - -Bad: - - function () - { - -Good: - - function () { - -If a block needs to wrap to the next line, use a curly brace. Don't -use it if it doesn't. - -Bad: - - if (foo) { bar() } - while (foo) - bar() - -Good: - - if (foo) bar() - while (foo) { - bar() - } - -## Semicolons - -Don't use them except in four situations: - -* `for (;;)` loops. They're actually required. -* null loops like: `while (something) ;` (But you'd better have a good - reason for doing that.) -* `case 'foo': doSomething(); break` -* In front of a leading `(` or `[` at the start of the line. - This prevents the expression from being interpreted - as a function call or property access, respectively. - -Some examples of good semicolon usage: - - ;(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() - } - -Note that starting lines with `-` and `+` also should be prefixed -with a semicolon, but this is much less common. - -## Comma First - -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: - - var magicWords = [ 'abracadabra' - , 'gesundheit' - , 'ventrilo' - ] - , spells = { 'fireball' : function () { setOnFire() } - , 'water' : function () { putOut() } - } - , a = 1 - , b = 'abc' - , etc - , somethingElse - -## Quotes -Use single quotes for strings except to avoid escaping. - -Bad: - - var notOk = "Just double quotes" - -Good: - - var ok = 'String contains "double" quotes' - var alsoOk = "String contains 'single' quotes or apostrophe" - -## Whitespace - -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. - -Don't leave trailing whitespace at the end of lines. Don't indent empty -lines. Don't use more spaces than are helpful. - -## Functions - -Use named functions. They make stack traces a lot easier to read. - -## Callbacks, Sync/async Style - -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. - -The callback should always be the last argument in the list. Its first -argument is the Error or null. - -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. - -## Errors - -Always create a new Error object with your message. Don't just return a -string message to the callback. Stack traces are handy. - -## Logging - -Logging is done using the [npmlog](https://github.com/npm/npmlog) -utility. - -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. - -Use appropriate log levels. See `npm-config(7)` and search for -"loglevel". - -## Case, naming, etc. - -Use `lowerCamelCase` for multiword identifiers when they refer to objects, -functions, methods, properties, or anything not specified in this section. - -Use `UpperCamelCase` for class names (things that you'd pass to "new"). - -Use `all-lower-hyphen-css-case` for multiword filenames and config keys. - -Use named functions. They make stack traces easier to follow. - -Use `CAPS_SNAKE_CASE` for constants, things that should never change -and are rarely used. - -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. - -## null, undefined, false, 0 - -Boolean variables and functions should always be either `true` or -`false`. Don't set it to 0 unless it's supposed to be a number. - -When something is intentionally missing or removed, set it to `null`. - -Don't set things to `undefined`. Reserve that value to mean "not yet -set to anything." - -Boolean objects are forbidden. - -## SEE ALSO - -* npm-developers(7) -* npm(1) |