npm-coding-style(7)

1NPM-CODING-STYLE(7)                                        NPM-CODING-STYLE(7)
2
3
4

NAME

6       npm-coding-style - npm's "funny" coding style
7

DESCRIPTION

9       npm's  coding  style  is a bit unconventional.  It is not different for
10       difference's sake,  but  rather  a  carefully  crafted  style  that  is
11       designed to reduce visual clutter and make bugs more apparent.
12
13       If you want to contribute to npm (which is very encouraged), you should
14       make your code conform to npm's style.
15
16       Note: this concerns npm's code not the specific packages that  you  can
17       download from the npm registry.
18

Line Length

20       Keep lines shorter than 80 characters.  It's better for lines to be too
21       short than to be too long.  Break up long  lists,  objects,  and  other
22       statements onto multiple lines.
23

Indentation

25       Two-spaces.   Tabs  are better, but they look like hell in web browsers
26       (and on GitHub), and node uses 2 spaces, so that's that.
27
28       Configure your editor appropriately.
29

Curly braces

31       Curly braces belong on the same line as  the  thing  that  necessitates
32       them.
33
34       Bad:
35
36         function ()
37         {
38
39       Good:
40
41         function () {
42
43       If  a  block  needs to wrap to the next line, use a curly brace.  Don't
44       use it if it doesn't.
45
46       Bad:
47
48         if (foo) { bar() }
49         while (foo)
50           bar()
51
52       Good:
53
54         if (foo) bar()
55         while (foo) {
56           bar()
57         }
58

Semicolons

60       Don't use them except in four situations:
61
62       · for (;;) loops.  They're actually required.
63
64       · null loops like: while (something) ; (But you'd better  have  a  good
65         reason for doing that.)
66
67       · case 'foo': doSomething(); break
68
69       · In front of a leading ( or [ at the start of the line.  This prevents
70         the expression from being interpreted as a function call or  property
71         access, respectively.
72
73
74       Some examples of good semicolon usage:
75
76         ;(x || y).doSomething()
77         ;[a, b, c].forEach(doSomething)
78         for (var i = 0; i < 10; i ++) {
79           switch (state) {
80             case 'begin': start(); continue
81             case 'end': finish(); break
82             default: throw new Error('unknown state')
83           }
84           end()
85         }
86
87       Note  that  starting  lines with - and + also should be prefixed with a
88       semicolon, but this is much less common.
89

Comma First

91       If there is a list of things separated by commas, and it  wraps  across
92       multiple  lines,  put the comma at the start of the next line, directly
93       below the token that starts the list.  Put the final token in the  list
94       on a line by itself.  For example:
95
96         var magicWords = [ 'abracadabra'
97                          , 'gesundheit'
98                          , 'ventrilo'
99                          ]
100           , spells = { 'fireball' : function () { setOnFire() }
101                      , 'water' : function () { putOut() }
102                      }
103           , a = 1
104           , b = 'abc'
105           , etc
106           , somethingElse
107

Quotes

109       Use single quotes for strings except to avoid escaping.
110
111       Bad:
112
113         var notOk = "Just double quotes"
114
115       Good:
116
117         var ok = 'String contains "double" quotes'
118         var alsoOk = "String contains 'single' quotes or apostrophe"
119

Whitespace

121       Put  a  single  space  in front of ( for anything other than a function
122       call.  Also use a single space wherever it makes things more readable.
123
124       Don't leave trailing whitespace at the  end  of  lines.   Don't  indent
125       empty lines.  Don't use more spaces than are helpful.
126

Functions

128       Use named functions.  They make stack traces a lot easier to read.
129

Callbacks, Sync/async Style

131       Use  the asynchronous/non-blocking versions of things as much as possi‐
132       ble.  It might make more sense for npm to use the synchronous fs  APIs,
133       but this way, the fs and http and child process stuff all uses the same
134       callback-passing methodology.
135
136       The callback should always be the last argument in the list.  Its first
137       argument is the Error or null.
138
139       Be  very  careful  never  to ever ever throw anything.  It's worse than
140       useless.  Just send the error message back as the first argument to the
141       callback.
142

Errors

144       Always  create a new Error object with your message.  Don't just return
145       a string message to the callback.  Stack traces are handy.
146

Logging

148       Logging is done using the npmlog https://github.com/npm/npmlog utility.
149
150       Please clean up logs when they are no longer helpful.   In  particular,
151       logging  the  same  object  over  and  over again is not helpful.  Logs
152       should report what's happening so that it's easier to track down  where
153       a fault occurs.
154
155       Use  appropriate  log levels.  See npm help 7 npm-config and search for
156       "loglevel".
157

Case, naming, etc.

159       Use  lowerCamelCase  for  multiword  identifiers  when  they  refer  to
160       objects,  functions,  methods, properties, or anything not specified in
161       this section.
162
163       Use UpperCamelCase for class names (things that you'd pass to "new").
164
165       Use all-lower-hyphen-css-case for multiword filenames and config keys.
166
167       Use named functions.  They make stack traces easier to follow.
168
169       Use CAPS_SNAKE_CASE for constants, things that should never change  and
170       are rarely used.
171
172       Use  a  single  uppercase  letter for function names where the function
173       would normally be anonymous, but needs to call itself recursively.   It
174       makes it clear that it's a "throwaway" function.
175

null, undefined, false, 0

177       Boolean  variables and functions should always be either true or false.
178       Don't set it to 0 unless it's supposed to be a number.
179
180       When something is intentionally missing or removed, set it to null.
181
182       Don't set things to undefined.  Reserve that value to mean "not yet set
183       to anything."
184
185       Boolean objects are forbidden.
186