deps/npm/html/doc/misc/npm-coding-style.html

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