deps/npm/man/man7/npm-coding-style.7

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