The data contained in this repository can be downloaded to your computer using one of several clients.
Please see the documentation of your version control software client for more information.

Please select the desired protocol below to get the URL.

This URL has Read-Only access.

Statistics
| Branch: | Revision:

main_repo / deps / npm / html / doc / coding-style.html @ 5aef65a9

History | View | Annotate | Download (7.18 KB)

1
<!doctype html>
2
<html>
3
  <title>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="../doc/coding-style.html">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="../doc/config.html">config(1)</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="../doc/developers.html">developers(1)</a></li><li><a href="../doc/faq.html">faq(1)</a></li><li><a href="../doc/npm.html">npm(1)</a></li></ul>
184
</div>
185
<p id="footer">coding-style &mdash; npm@1.2.10</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>
217
</body></html>