Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 256 lines (255 sloc) 5.95 kb
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
1 .\" Generated with Ronnjs/v0.1
2 .\" http://github.com/kapouer/ronnjs/
90dd817 @isaacs Coding style guideline.
isaacs authored
3 .
0ce9853 @isaacs make doc
isaacs authored
4 .TH "NPM\-CODING\-STYLE" "1" "March 2011" "" ""
90dd817 @isaacs Coding style guideline.
isaacs authored
5 .
6 .SH "NAME"
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
7 \fBnpm-coding-style\fR \-\- npm\'s "funny" coding style
90dd817 @isaacs Coding style guideline.
isaacs authored
8 .
9 .SH "DESCRIPTION"
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
10 npm\'s coding style is a bit unconventional\. It is not different for
11 difference\'s sake, but rather a carefully crafted style that is
12 designed to reduce visual clutter and make bugs more apparent\.
90dd817 @isaacs Coding style guideline.
isaacs authored
13 .
14 .P
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
15 If you want to contribute to npm (which is very encouraged), you should
16 make your code conform to npm\'s style\.
90dd817 @isaacs Coding style guideline.
isaacs authored
17 .
18 .SH "Line Length"
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
19 Keep lines shorter than 80 characters\. It\'s better for lines to be
20 too short than to be too long\. Break up long lists, objects, and other
21 statements onto multiple lines\.
90dd817 @isaacs Coding style guideline.
isaacs authored
22 .
23 .SH "Indentation"
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
24 Two\-spaces\. Tabs are better, but they look like hell in web browsers
25 (and on github), and node uses 2 spaces, so that\'s that\.
90dd817 @isaacs Coding style guideline.
isaacs authored
26 .
27 .P
e937a72 @isaacs Update all man pages using new version of ronn
isaacs authored
28 Configure your editor appropriately\.
90dd817 @isaacs Coding style guideline.
isaacs authored
29 .
30 .SH "Curly braces"
e937a72 @isaacs Update all man pages using new version of ronn
isaacs authored
31 Curly braces belong on the same line as the thing that necessitates them\.
90dd817 @isaacs Coding style guideline.
isaacs authored
32 .
33 .P
34 Bad:
35 .
36 .IP "" 4
37 .
38 .nf
39 function ()
40 {
41 .
42 .fi
43 .
44 .IP "" 0
45 .
46 .P
47 Good:
48 .
49 .IP "" 4
50 .
51 .nf
52 function () {
53 .
54 .fi
55 .
56 .IP "" 0
57 .
58 .P
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
59 If a block needs to wrap to the next line, use a curly brace\. Don\'t
60 use it if it doesn\'t\.
90dd817 @isaacs Coding style guideline.
isaacs authored
61 .
62 .P
63 Bad:
64 .
65 .IP "" 4
66 .
67 .nf
68 if (foo) { bar() }
69 while (foo)
70 bar()
71 .
72 .fi
73 .
74 .IP "" 0
75 .
76 .P
77 Good:
78 .
79 .IP "" 4
80 .
81 .nf
82 if (foo) bar()
83 while (foo) {
84 bar()
85 }
86 .
87 .fi
88 .
89 .IP "" 0
90 .
91 .SH "Semicolons"
13d7966 @isaacs Coding style updates.
isaacs authored
92 Don\'t use them except in four situations:
90dd817 @isaacs Coding style guideline.
isaacs authored
93 .
94 .IP "\(bu" 4
13d7966 @isaacs Coding style updates.
isaacs authored
95 \fBfor (;;)\fR loops\. They\'re actually required\.
96 .
97 .IP "\(bu" 4
98 null loops like: \fBwhile (something) ;\fR (But you\'d better have a good
99 reason for doing that\.)
90dd817 @isaacs Coding style guideline.
isaacs authored
100 .
101 .IP "\(bu" 4
102 case "foo": doSomething(); break
103 .
104 .IP "\(bu" 4
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
105 In front of a leading ( or [ at the start of the line\.
106 This prevents the expression from being interpreted
107 as a function call or property access, respectively\.
90dd817 @isaacs Coding style guideline.
isaacs authored
108 .
109 .IP "" 0
110 .
111 .P
112 Some examples of good semicolon usage:
113 .
114 .IP "" 4
115 .
116 .nf
e937a72 @isaacs Update all man pages using new version of ronn
isaacs authored
117 ;(x || y)\.doSomething()
118 ;[a, b, c]\.forEach(doSomething)
90dd817 @isaacs Coding style guideline.
isaacs authored
119 for (var i = 0; i < 10; i ++) {
120 switch (state) {
121 case "begin": start(); continue
122 case "end": finish(); break
123 default: throw new Error("unknown state")
124 }
125 end()
126 }
127 .
128 .fi
129 .
130 .IP "" 0
131 .
9dd1d79 @isaacs make doc
isaacs authored
132 .P
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
133 Note that starting lines with \fB\-\fR and \fB+\fR also should be prefixed
134 with a semicolon, but this is much less common\.
9dd1d79 @isaacs make doc
isaacs authored
135 .
90dd817 @isaacs Coding style guideline.
isaacs authored
136 .SH "Comma First"
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
137 If there is a list of things separated by commas, and it wraps
138 across multiple lines, put the comma at the start of the next
139 line, directly below the token that starts the list\. Put the
140 final token in the list on a line by itself\. For example:
90dd817 @isaacs Coding style guideline.
isaacs authored
141 .
142 .IP "" 4
143 .
144 .nf
145 var magicWords = [ "abracadabra"
146 , "gesundheit"
147 , "ventrilo"
148 ]
149 , spells = { "fireball" : function () { setOnFire() }
150 , "water" : function () { putOut() }
151 }
152 , a = 1
153 , b = "abc"
154 , etc
155 , somethingElse
156 .
157 .fi
158 .
159 .IP "" 0
160 .
161 .SH "Whitespace"
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
162 Put a single space in front of ( for anything other than a function call\.
163 Also use a single space wherever it makes things more readable\.
90dd817 @isaacs Coding style guideline.
isaacs authored
164 .
165 .P
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
166 Don\'t leave trailing whitespace at the end of lines\. Don\'t indent empty
167 lines\. Don\'t use more spaces than are helpful\.
90dd817 @isaacs Coding style guideline.
isaacs authored
168 .
169 .SH "Functions"
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
170 Use named functions\. They make stack traces a lot easier to read\.
90dd817 @isaacs Coding style guideline.
isaacs authored
171 .
172 .SH "Callbacks, Sync/async Style"
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
173 Use the asynchronous/non\-blocking versions of things as much as possible\.
174 It might make more sense for npm to use the synchronous fs APIs, but this
175 way, the fs and http and child process stuff all uses the same callback\-passing
176 methodology\.
90dd817 @isaacs Coding style guideline.
isaacs authored
177 .
178 .P
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
179 The callback should always be the last argument in the list\. Its first
180 argument is the Error or null\.
90dd817 @isaacs Coding style guideline.
isaacs authored
181 .
182 .P
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
183 Be very careful never to ever ever throw anything\. It\'s worse than useless\.
184 Just send the error message back as the first argument to the callback\.
90dd817 @isaacs Coding style guideline.
isaacs authored
185 .
186 .SH "Errors"
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
187 Always create a new Error object with your message\. Don\'t just return a
188 string message to the callback\. Stack traces are handy\.
90dd817 @isaacs Coding style guideline.
isaacs authored
189 .
190 .P
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
191 Use the \fBrequire("\./utils/log")\.er\fR function\. It takes a callback and an
192 error message, and returns an object that will report the message in the
193 event of a failure\. It\'s quite handy\.
90dd817 @isaacs Coding style guideline.
isaacs authored
194 .
195 .IP "" 4
196 .
197 .nf
198 function myThing (args, cb) {
199 getData(args, function (er, data) {
e937a72 @isaacs Update all man pages using new version of ronn
isaacs authored
200 if (er) return log\.er(cb, "Couldn\'t get data")(er)
90dd817 @isaacs Coding style guideline.
isaacs authored
201 doSomethingElse(data, cb)
202 })
203 }
204 function justHasToWork (cb) {
e937a72 @isaacs Update all man pages using new version of ronn
isaacs authored
205 doSomething(log\.er(cb, "the doSomething failed\."))
90dd817 @isaacs Coding style guideline.
isaacs authored
206 }
207 .
208 .fi
209 .
210 .IP "" 0
211 .
212 .SH "Logging"
f2ccd17 @isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
213 Please clean up logs when they are no longer helpful\. In particular,
214 logging the same object over and over again is not helpful\. Logs should
215 report what\'s happening so that it\'s easier to track down where a fault
216 occurs\.
13d7966 @isaacs Coding style updates.
isaacs authored
217 .
218 .P
219 Use appropriate log levels\. The default log() function logs at the
220 "info" level\. See \fBnpm help config\fR and search for "loglevel"\.
221 .
222 .SH "Case, naming, etc\."
223 Use lowerCamelCase for multiword identifiers when they refer to objects,
224 functions, methods, members, or anything not specified in this section\.
225 .
226 .P
227 Use UpperCamelCase for class names (things that you\'d pass to "new")\.
228 .
229 .P
230 Use all\-lower\-hyphen\-css\-case for multiword filenames and config keys\.
231 .
232 .P
233 Use named functions\. They make stack traces easier to follow\.
234 .
235 .P
236 Use CAPS\fISNAKE\fRCASE for constants, things that should never change
237 and are rarely used\.
238 .
239 .P
240 Use a single uppercase letter for function names where the function
241 would normally be anonymous, but needs to call itself recursively\. It
242 makes it clear that it\'s a "throwaway" function\.
0ce9853 @isaacs make doc
isaacs authored
243 .
244 .SH "null, undefined, false, 0"
245 Boolean variables and functions should always be either \fBtrue\fR or \fBfalse\fR\|\. Don\'t set it to 0 unless it\'s supposed to be a number\.
246 .
247 .P
248 When something is intentionally missing or removed, set it to \fBnull\fR\|\.
249 .
250 .P
251 Don\'t set things to \fBundefined\fR\|\. Reserve that value to mean "not yet
252 set to anything\."
253 .
254 .P
255 Boolean objects are verboten\.
Something went wrong with that request. Please try again.