Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 395 lines (275 sloc) 7.407 kb
cec8d36 @Raynos updated style guide
authored
1 # Raynos coding style
2
3 Forked from [idiomatic.js][1]
4
5 ## Table of Contents
6
7 - [Whitespace](#whitespace)
8 - [Beautiful Syntax](#spacing)
9 - [Conditional Evaluation](#cond)
10 - [Practical Style](#practical)
11 - [Naming](#naming)
12 - [Misc](#misc)
13 - [Comments](#comments)
14
15
16 ## Idiomatic Style Manifesto
17
18
19 1. <a name="whitespace">Whitespace</a>
20
21 - 4 spaces per indent. No tabs.
22
23 2. <a name="spacing">Beautiful Syntax</a>
24
25 A. Parens, Braces, Linebreaks
26
27 ```javascript
28
29 // if/else/for/while/try always have braces and span multiple lines
30 // this encourages readability
31 // There shall be a space between if and ( and ) and {.
32 // There shall be no space between ( and condition and condition and )
33
34 // 2.A.1.1
35 // Use whitespace to promote readability
36
37 if (condition) {
38 // statements
39 }
40
41 while (condition) {
42 // statements
43 }
44
45 for (var i = 0; i < 100; i++) {
46 // statements
47 }
48
49
50 if (true) {
51 // statements
52 } else {
53 // statements
54 }
55 ```
56
57
58 B. Assignments, Declarations, Functions ( Named, Expression, Constructor )
59
60 ```javascript
61
62 // 2.B.1.1
63 // Variables
64 var foo = "bar",
65 num = 1,
66 undef;
67
68 // Literal notations:
69 var array = [],
70 object = {};
71
72
73 // 2.B.1.2
74 // Using only one `var` per scope (logical) promotes readability
75 // and keeps your declaration list free of clutter (also saves a few bytes)
76 // Note logical scope is logical scope. Declare variables above their first
77 // use. Never write two var statements after each other
78
79 // Bad
80 var foo = "";
81 var bar = "";
82 var qux;
83
84 // Good
85 var foo = "",
86 bar = "",
87 quux;
88 ```
89
90 ```javascript
91
92 // 2.B.2.1
93 // Named Function Declaration
94 function foo(arg1, argN) {
b080a50 @Raynos fixed style
authored
95 /* code */
cec8d36 @Raynos updated style guide
authored
96 }
97
98 // Usage
99 foo(arg1, argN);
100
101
102 // 2.B.2.2
103 // Named Function (w/ callback argument)
104 // callbacks will always be the last argument
105 function bar(arg1, callback) {
106 if (arg1 && callback) {
107 callback();
108 }
109 }
110
111 // Usage
112 bar(arg1, callback);
113
114 function callback() {
115 // callback statements
116 }
117
118
119 // 2.B.2.3
120 // Function Expression
121 // Never use non-anonymous function expressions
122 // Always favour function declarations.
b080a50 @Raynos fixed style
authored
123 // A exception is the desire to have a single anonymous function in
cec8d36 @Raynos updated style guide
authored
124 // global scope
125
126 (function _yourSingleGlobalAnonymousFunctionClosure () {
127 /* code */
b080a50 @Raynos fixed style
authored
128 }())
cec8d36 @Raynos updated style guide
authored
129
130 // Another exception is NFE on an object literal
131
132 var literal = {
133 method: function _method() {
134
135 }
136 };
137
138 // 2.B.2.4
139 // Constructor definition
140 // Don't use them. Use prototypical OO
141
142 E. End of Lines and Empty Lines
143
144 Whitespace can ruin diffs and make changesets impossible to read. Consider incorporating a pre-commit hook that removes end-of-line whitespace and blanks spaces on empty lines automatically.
b080a50 @Raynos fixed style
authored
145 ```
cec8d36 @Raynos updated style guide
authored
146
147 3. <a name="cond">Conditional Evaluation</a>
148
149 Favour using truthy and falsey checks rather then verbose checks where
150 applicable
151
152
153 ```javascript
154
155 // 3.1.1
156 // When only evaluating that an array has length,
157 // instead of this:
e1ca84a @Raynos updated guide
authored
158 if (array.length > 0) ...
cec8d36 @Raynos updated style guide
authored
159
160 // ...evaluate truthiness, like this:
e1ca84a @Raynos updated guide
authored
161 if (array.length) ...
cec8d36 @Raynos updated style guide
authored
162 ```
163
164
165 ```javascript
166
167 // 3.2.1
168 // Type coercion and evaluation notes
169
f82ca38 @Raynos cleaned up style
authored
170 Always use === even for x == null favour the more verbose alternative
cec8d36 @Raynos updated style guide
authored
171
172 x === null || x === undefined
173
174 ```
175
176 4. <a name="practical">Practical Style</a>
177
178 ```javascript
179
180 // 4.1.1
181 // A Practical Module
182
183 (function _anonymousWrapper(global) {
184 "use strict";
185
186 var SomeObject = {
187 string: "a string",
188 object: {
189 lang: "en-US"
190 },
191 method: function _namedMethod() {
192 return 42;
193 }
194 };
195
196 // Other things might happen here
197
198 // expose our module through a module loader or global
199 if (typeof module !== "undefined" && module.exports) {
200 module.exports = SomeObject;
201 } else {
b080a50 @Raynos fixed style
authored
202 global.SomeObject = SomeObject;
cec8d36 @Raynos updated style guide
authored
203 }
204
b080a50 @Raynos fixed style
authored
205 }(global || window));
cec8d36 @Raynos updated style guide
authored
206
207
208 // 4.2.1
209 // A Practical Prototype
210
211 (function( global ) {
212
213 var SomeObject = {
214 constructor: function _constructor(foo) {
215 this.foo = foo;
216 return this;
217 },
218 /* We do not use useless getter/setter methods ever.
219 getFoo: function _getFoo() { ... }
220 */
221 manipulate: function _manipulate(id) {
222 foo += id;
223 }
224 };
225
226 // For easier inheritance use pd
227 SomeObject = pd.Base.make(SomeObject);
228
229 // expose our module through a module loader or global
230 if (typeof module !== "undefined" && module.exports) {
231 module.exports = SomeObject;
232 } else {
b080a50 @Raynos fixed style
authored
233 global.SomeObject = SomeObject;
cec8d36 @Raynos updated style guide
authored
234 }
235
b080a50 @Raynos fixed style
authored
236 }( global || window ));
cec8d36 @Raynos updated style guide
authored
237
238 ```
239
9d15dcb @Raynos Added links
authored
240 Examples:
241
242 - [pd][2]
243 - [after][3]
244
cec8d36 @Raynos updated style guide
authored
245 5. <a name="naming">Naming</a>
246
247 Use sensible, readable names
248
b080a50 @Raynos fixed style
authored
249 ```javascript
cec8d36 @Raynos updated style guide
authored
250 // 5.1
251 // Naming style
252
253 functionNamesLikeThis;
254 variableNamesLikeThis;
255 PrototypeObjectNamesLikeThis;
256 methodNamesLikeThis;
257 SYMBOLIC_CONSTANTS_LIKE_THIS;
258 ```
259
260 6. <a name="misc">Misc</a>
261
262 A. Early returns promote code readability with negligible performance difference
263
264 ```javascript
265
266 // 6.A.1.1
267 // Bad:
268 function returnLate( foo ) {
269 var ret;
270
271 if ( foo ) {
272 ret = "foo";
273 } else {
274 ret = "quux";
275 }
276 return ret;
277 }
278
279 // Good:
280
281 function returnEarly( foo ) {
282
283 if ( foo ) {
284 return "foo";
285 }
286 return "quux";
287 }
288
289 B. Use new lines to split up logical blocks in functions
290
291 // 6.B.1.1
292 // Bad:
293 function extend(target) {
294 var objs = slice.call(arguments, 1);
295 objs.forEach(extendTarget);
296 return target;
297 }
298
299 // Good:
300
301 function extend(target) {
302 var objs = slice.call(arguments, 1);
303
304 objs.forEach(extendTarget);
305
306 return target;
307 }
308
309 // In general, variable declarations have a new line after them
310 // Return statements have a new line after them
311 // lines of code should be broken up with a new line
312 // unless they are manipulation the same object
b080a50 @Raynos fixed style
authored
313 // Don't add a new at the start of a function or the end
314 // unless it's the global wrapper
315
316 // Good:
317
318 (function _anonWrapper() {
319
320 function name(param) {
321 var o = param;
322
323 o++;
324
325 return o;
326 }
327
328 }());
cec8d36 @Raynos updated style guide
authored
329
330 C. inner Function declarations at the bottom
331
332 // 6.C.1.1
333
334 // Bad:
335
336 function extend(target) {
337 var objs = slice.call(arguments, 1);
338
339 function extendTarget(obj) {
340 var props = getOwnPropertyNames(obj);
341 props.forEach(function (key) {
342 target[key] = obj[key];
343 });
344 }
345
346 objs.forEach(extendTarget);
347
348 return target;
349 }
350
351 // Very Bad:
352
353 function extend(target) {
354 var objs = slice.call(arguments, 1);
355
356 objs.forEach(function (obj) {
357 var props = getOwnPropertyNames(obj);
358 props.forEach(function (key) {
359 target[key] = obj[key];
360 });
361 });
362
363 return target;
364 }
365
366 // Good:
367
368 function extend(target) {
369 var objs = slice.call(arguments, 1);
370
371 objs.forEach(extendTarget);
372
373 return target;
374
375 function extendTarget(obj) {
376 var props = getOwnPropertyNames(obj);
377 props.forEach(function (key) {
378 target[key] = obj[key];
379 });
380 }
381 }
382
383 D. Always "use strict";
384
e1ca84a @Raynos updated guide
authored
385 E. line length shall be 100 characters, no more, no exceptions.
386
cec8d36 @Raynos updated style guide
authored
387 ```
388
389 7. <a name="comments">Comments</a>
390
391 - single block comment above a function
392
9d15dcb @Raynos Added links
authored
393 [1]: https://github.com/rwldrn/idiomatic.js
394 [2]: https://github.com/Raynos/pd/blob/e1ca84aba1282f0bd62112050adb4d5263a0ea33/src/pd.js
395 [3]: https://github.com/Raynos/after.js/blob/7054d2788aa2175b6178ea31e260f6e9c6fc01c4/src/after.js
Something went wrong with that request. Please try again.