org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/man/man7/npm-coding-style.7

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