mirror of
https://github.com/titanscouting/tra-analysis.git
synced 2024-11-10 15:04:45 +00:00
223 lines
5.6 KiB
Groff
223 lines
5.6 KiB
Groff
.TH "NPM\-CODING\-STYLE" "7" "December 2018" "" ""
|
|
.SH "NAME"
|
|
\fBnpm-coding-style\fR \- npm's "funny" coding style
|
|
.SH DESCRIPTION
|
|
.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
|
|
If you want to contribute to npm (which is very encouraged), you should
|
|
make your code conform to npm's style\.
|
|
.P
|
|
Note: this concerns npm's code not the specific packages that you can download from the npm registry\.
|
|
.SH Line Length
|
|
.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\.
|
|
.SH Indentation
|
|
.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
|
|
Configure your editor appropriately\.
|
|
.SH Curly braces
|
|
.P
|
|
Curly braces belong on the same line as the thing that necessitates them\.
|
|
.P
|
|
Bad:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
function ()
|
|
{
|
|
.fi
|
|
.RE
|
|
.P
|
|
Good:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
function () {
|
|
.fi
|
|
.RE
|
|
.P
|
|
If a block needs to wrap to the next line, use a curly brace\. Don't
|
|
use it if it doesn't\.
|
|
.P
|
|
Bad:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
if (foo) { bar() }
|
|
while (foo)
|
|
bar()
|
|
.fi
|
|
.RE
|
|
.P
|
|
Good:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
if (foo) bar()
|
|
while (foo) {
|
|
bar()
|
|
}
|
|
.fi
|
|
.RE
|
|
.SH Semicolons
|
|
.P
|
|
Don't use them except in four situations:
|
|
.RS 0
|
|
.IP \(bu 2
|
|
\fBfor (;;)\fP loops\. They're actually required\.
|
|
.IP \(bu 2
|
|
null loops like: \fBwhile (something) ;\fP (But you'd better have a good
|
|
reason for doing that\.)
|
|
.IP \(bu 2
|
|
\fBcase 'foo': doSomething(); break\fP
|
|
.IP \(bu 2
|
|
In front of a leading \fB(\fP or \fB[\fP at the start of the line\.
|
|
This prevents the expression from being interpreted
|
|
as a function call or property access, respectively\.
|
|
|
|
.RE
|
|
.P
|
|
Some examples of good semicolon usage:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
;(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()
|
|
}
|
|
.fi
|
|
.RE
|
|
.P
|
|
Note that starting lines with \fB\-\fP and \fB+\fP also should be prefixed
|
|
with a semicolon, but this is much less common\.
|
|
.SH Comma First
|
|
.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
|
|
.RS 2
|
|
.nf
|
|
var magicWords = [ 'abracadabra'
|
|
, 'gesundheit'
|
|
, 'ventrilo'
|
|
]
|
|
, spells = { 'fireball' : function () { setOnFire() }
|
|
, 'water' : function () { putOut() }
|
|
}
|
|
, a = 1
|
|
, b = 'abc'
|
|
, etc
|
|
, somethingElse
|
|
.fi
|
|
.RE
|
|
.SH Quotes
|
|
.P
|
|
Use single quotes for strings except to avoid escaping\.
|
|
.P
|
|
Bad:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
var notOk = "Just double quotes"
|
|
.fi
|
|
.RE
|
|
.P
|
|
Good:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
var ok = 'String contains "double" quotes'
|
|
var alsoOk = "String contains 'single' quotes or apostrophe"
|
|
.fi
|
|
.RE
|
|
.SH Whitespace
|
|
.P
|
|
Put a single space in front of \fB(\fP for anything other than a function call\.
|
|
Also use a single space wherever it makes things more readable\.
|
|
.P
|
|
Don't leave trailing whitespace at the end of lines\. Don't indent empty
|
|
lines\. Don't use more spaces than are helpful\.
|
|
.SH Functions
|
|
.P
|
|
Use named functions\. They make stack traces a lot easier to read\.
|
|
.SH Callbacks, Sync/async Style
|
|
.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
|
|
The callback should always be the last argument in the list\. Its first
|
|
argument is the Error or null\.
|
|
.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\.
|
|
.SH Errors
|
|
.P
|
|
Always create a new Error object with your message\. Don't just return a
|
|
string message to the callback\. Stack traces are handy\.
|
|
.SH Logging
|
|
.P
|
|
Logging is done using the npmlog \fIhttps://github\.com/npm/npmlog\fR
|
|
utility\.
|
|
.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
|
|
Use appropriate log levels\. See npm help 7 \fBnpm\-config\fP and search for
|
|
"loglevel"\.
|
|
.SH Case, naming, etc\.
|
|
.P
|
|
Use \fBlowerCamelCase\fP for multiword identifiers when they refer to objects,
|
|
functions, methods, properties, or anything not specified in this section\.
|
|
.P
|
|
Use \fBUpperCamelCase\fP for class names (things that you'd pass to "new")\.
|
|
.P
|
|
Use \fBall\-lower\-hyphen\-css\-case\fP for multiword filenames and config keys\.
|
|
.P
|
|
Use named functions\. They make stack traces easier to follow\.
|
|
.P
|
|
Use \fBCAPS_SNAKE_CASE\fP for constants, things that should never change
|
|
and are rarely used\.
|
|
.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\.
|
|
.SH null, undefined, false, 0
|
|
.P
|
|
Boolean variables and functions should always be either \fBtrue\fP or
|
|
\fBfalse\fP\|\. Don't set it to 0 unless it's supposed to be a number\.
|
|
.P
|
|
When something is intentionally missing or removed, set it to \fBnull\fP\|\.
|
|
.P
|
|
Don't set things to \fBundefined\fP\|\. Reserve that value to mean "not yet
|
|
set to anything\."
|
|
.P
|
|
Boolean objects are forbidden\.
|
|
.SH SEE ALSO
|
|
.RS 0
|
|
.IP \(bu 2
|
|
npm help 7 developers
|
|
.IP \(bu 2
|
|
npm help npm
|
|
|
|
.RE
|
|
|