org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/doc/misc/npm-coding-style.md

   1 npm-coding-style(7) -- npm's "funny" coding style
   2 =================================================
   3
   4 ## DESCRIPTION
   5
   6 npm's coding style is a bit unconventional.  It is not different for
   7 difference's sake, but rather a carefully crafted style that is
   8 designed to reduce visual clutter and make bugs more apparent.
   9
  10 If you want to contribute to npm (which is very encouraged), you should
  11 make your code conform to npm's style.
  12
  13 Note: this concerns npm's code not the specific packages that you can download from the npm registry.
  14
  15 ## Line Length
  16
  17 Keep lines shorter than 80 characters.  It's better for lines to be
  18 too short than to be too long.  Break up long lists, objects, and other
  19 statements onto multiple lines.
  20
  21 ## Indentation
  22
  23 Two-spaces.  Tabs are better, but they look like hell in web browsers
  24 (and on GitHub), and node uses 2 spaces, so that's that.
  25
  26 Configure your editor appropriately.
  27
  28 ## Curly braces
  29
  30 Curly braces belong on the same line as the thing that necessitates them.
  31
  32 Bad:
  33
  34     function ()
  35     {
  36
  37 Good:
  38
  39     function () {
  40
  41 If a block needs to wrap to the next line, use a curly brace.  Don't
  42 use it if it doesn't.
  43
  44 Bad:
  45
  46     if (foo) { bar() }
  47     while (foo)
  48       bar()
  49
  50 Good:
  51
  52     if (foo) bar()
  53     while (foo) {
  54       bar()
  55     }
  56
  57 ## Semicolons
  58
  59 Don't use them except in four situations:
  60
  61 * `for (;;)` loops.  They're actually required.
  62 * null loops like: `while (something) ;` (But you'd better have a good
  63   reason for doing that.)
  64 * `case "foo": doSomething(); break`
  65 * In front of a leading `(` or `[` at the start of the line.
  66   This prevents the expression from being interpreted
  67   as a function call or property access, respectively.
  68
  69 Some examples of good semicolon usage:
  70
  71     ;(x || y).doSomething()
  72     ;[a, b, c].forEach(doSomething)
  73     for (var i = 0; i < 10; i ++) {
  74       switch (state) {
  75         case "begin": start(); continue
  76         case "end": finish(); break
  77         default: throw new Error("unknown state")
  78       }
  79       end()
  80     }
  81
  82 Note that starting lines with `-` and `+` also should be prefixed
  83 with a semicolon, but this is much less common.
  84
  85 ## Comma First
  86
  87 If there is a list of things separated by commas, and it wraps
  88 across multiple lines, put the comma at the start of the next
  89 line, directly below the token that starts the list.  Put the
  90 final token in the list on a line by itself.  For example:
  91
  92     var magicWords = [ "abracadabra"
  93                      , "gesundheit"
  94                      , "ventrilo"
  95                      ]
  96       , spells = { "fireball" : function () { setOnFire() }
  97                  , "water" : function () { putOut() }
  98                  }
  99       , a = 1
 100       , b = "abc"
 101       , etc
 102       , somethingElse
 103
 104 ## Whitespace
 105
 106 Put a single space in front of ( for anything other than a function call.
 107 Also use a single space wherever it makes things more readable.
 108
 109 Don't leave trailing whitespace at the end of lines.  Don't indent empty
 110 lines.  Don't use more spaces than are helpful.
 111
 112 ## Functions
 113
 114 Use named functions.  They make stack traces a lot easier to read.
 115
 116 ## Callbacks, Sync/async Style
 117
 118 Use the asynchronous/non-blocking versions of things as much as possible.
 119 It might make more sense for npm to use the synchronous fs APIs, but this
 120 way, the fs and http and child process stuff all uses the same callback-passing
 121 methodology.
 122
 123 The callback should always be the last argument in the list.  Its first
 124 argument is the Error or null.
 125
 126 Be very careful never to ever ever throw anything.  It's worse than useless.
 127 Just send the error message back as the first argument to the callback.
 128
 129 ## Errors
 130
 131 Always create a new Error object with your message.  Don't just return a
 132 string message to the callback.  Stack traces are handy.
 133
 134 ## Logging
 135
 136 Logging is done using the [npmlog](https://github.com/npm/npmlog)
 137 utility.
 138
 139 Please clean up logs when they are no longer helpful.  In particular,
 140 logging the same object over and over again is not helpful.  Logs should
 141 report what's happening so that it's easier to track down where a fault
 142 occurs.
 143
 144 Use appropriate log levels.  See `npm-config(7)` and search for
 145 "loglevel".
 146
 147 ## Case, naming, etc.
 148
 149 Use `lowerCamelCase` for multiword identifiers when they refer to objects,
 150 functions, methods, properties, or anything not specified in this section.
 151
 152 Use `UpperCamelCase` for class names (things that you'd pass to "new").
 153
 154 Use `all-lower-hyphen-css-case` for multiword filenames and config keys.
 155
 156 Use named functions.  They make stack traces easier to follow.
 157
 158 Use `CAPS_SNAKE_CASE` for constants, things that should never change
 159 and are rarely used.
 160
 161 Use a single uppercase letter for function names where the function
 162 would normally be anonymous, but needs to call itself recursively.  It
 163 makes it clear that it's a "throwaway" function.
 164
 165 ## null, undefined, false, 0
 166
 167 Boolean variables and functions should always be either `true` or
 168 `false`.  Don't set it to 0 unless it's supposed to be a number.
 169
 170 When something is intentionally missing or removed, set it to `null`.
 171
 172 Don't set things to `undefined`.  Reserve that value to mean "not yet
 173 set to anything."
 174
 175 Boolean objects are verboten.
 176
 177 ## SEE ALSO
 178
 179 * npm-developers(7)
 180 * npm-faq(7)
 181 * npm(1)