├── .jshintrc └── README.md /.jshintrc: -------------------------------------------------------------------------------- 1 | { 2 | "camelcase" : true, 3 | "indent": 2, 4 | "undef": true, 5 | "quotmark": "single", 6 | "maxlen": 80, 7 | "trailing": true, 8 | "curly": true 9 | } -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | JavaScript, the winning style 2 | ============================= 3 | 4 | _NOTE_: This 'research' was originally published as a blog article at http://seravo.fi/2013/javascript-the-winning-style and then transformed into a public Git repo on suggestion by [Eric Elliott](http://ericleads.com/). 5 | 6 | 7 | If your code is easy to read, there will be fewer bugs, any remaining bugs will be easier to debug and new coders will have a lower barrier to participate in your project. Everybody agrees that investing a bit of time to following an agreed-upon coding style is worth all the benefits it yields. Unlike Python and some other languages, JavaScript does not have an authoritative style guide. Instead there are several popular ones: 8 | 9 | * [Google JavaScript Style Guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml) 10 | * [npm’s coding style](https://docs.npmjs.com/misc/coding-style) 11 | * [Felix’s Node.js Style Guide](https://github.com/felixge/node-style-guide) 12 | * [Idiomatic JavaScript](https://github.com/rwldrn/idiomatic.js/) 13 | * [jQuery JavaScript Style Guide](http://contribute.jquery.org/style-guide/js/) 14 | * [Douglas Crockford’s JavaScript coding style](http://javascript.crockford.com/code.html) 15 | 16 | Then of course, there are also the default settings chosen in JavaScript syntax checkers JSLint and JSHint. The question is, what is the ultimate JavaScript style to rule them all? Let’s make a consensus based on these six style guides. 17 | 18 | Indentation 19 | ----------- 20 | Two spaces, not longer and no tabs: Google, npm, Node.js, Idiomatic 21 | 22 | Tabs: jQuery 23 | 24 | Four spaces: Crockford 25 | 26 | Spaces between arguments and expressions 27 | ---------------------------------------- 28 | Use sparingly like below: Google, npm, Node.js 29 | ```js 30 | project.MyClass = function(arg1, arg2) { 31 | ``` 32 | Use excessive white space like below: Idiomatic, jQuery 33 | ```js 34 | for ( i = 0; i < length; i++ ) { 35 | ``` 36 | No expressed opinion: Crockford 37 | 38 | Many guides remind not to have any trailing spaces! 39 | 40 | Line length 41 | ----------- 42 | Max 80 characters: Google, npm, Node.js, Crockford 43 | 44 | When wrapping, other indentation than two spaces is allowed to for example align function arguments to the position where the first function argument was. Another option is to use four spaces instead of two when word wrapping long lines. 45 | 46 | No expressed opinion: jQuery, Idiomatic 47 | 48 | Semicolons 49 | ---------- 50 | Always use semicolons and don’t rely on implicit insertion: Google, Node.js, Crockford 51 | 52 | Don’t use except in some situations: npm 53 | 54 | No expressed opinion: jQuery, Idiomatic 55 | 56 | Comments 57 | -------- 58 | JSDoc conventions: Google, Idiomatic 59 | 60 | In the Idiomatic Style Guide also simpler comments are allowed, but JSDoc encouraged. 61 | 62 | No expressed opinion: npm, Node.js, jQuery, Crockford 63 | 64 | Quotes 65 | ------ 66 | Prefer `'` over `"`: Google, Node.js 67 | 68 | Double quotes: jQuery 69 | 70 | No expressed opinion: npm, Idiomatic, Crockford 71 | 72 | Variable declarations 73 | --------------------- 74 | One per line and no commas: Node.js 75 | ```js 76 | var foo = ''; 77 | var bar = ''; 78 | ``` 79 | Multiple in one go with line ending commas like below: Idiomatic, jQuery 80 | ```js 81 | var foo = "", 82 | bar = "", 83 | quux; 84 | ``` 85 | Multiple in one go, line ending commas and four spaces indentation: Crockford 86 | ```js 87 | var foo = "", 88 | bar = "", 89 | quux; 90 | ``` 91 | Start with comma: npm 92 | ```js 93 | var foo = "" 94 | , bar = "" 95 | , quux; 96 | ``` 97 | No expressed opinion: Google 98 | 99 | Braces 100 | ------ 101 | Use opening brace on the same line: Google, npm, Node, Idiomatic, jQuery, Crockford 102 | ```js 103 | function thisIsBlock() { 104 | ``` 105 | These also imply that braces should be used in all cases. 106 | 107 | The npm style guide states that braces should only be used if a block needs to wrap to the next line. 108 | 109 | Globals 110 | ------- 111 | Don’t use globals: Google, Crockford 112 | 113 | Google says: “Global name conflicts are difficult to debug, and can cause intractable problems when two projects try to integrate. In order to make it possible to share common JavaScript code, we’ve adopted conventions to prevent collisions.” 114 | 115 | Crockford states that implied global variables should never be used. 116 | 117 | No expressed opinion: Idiomatic, jQuery, npm, Node 118 | 119 | Naming 120 | ====== 121 | 122 | Variables 123 | --------- 124 | 125 | Start first word lowercase and after that all words start with uppercase letter (Camel case): Google, npm, Node, Idiomatic 126 | ```js 127 | var foo = ""; 128 | var fooName = ""; 129 | ``` 130 | Constants 131 | --------- 132 | Use uppercase with underscore: Google, npm, Node, Idiomatic 133 | ```js 134 | var CONSTANT = 'VALUE'; 135 | var CONSTANT_NAME = 'VALUE'; 136 | ``` 137 | No expressed opinion: jQuery, Crockford 138 | 139 | Functions 140 | --------- 141 | Start first word lowercase and after that all words start with uppercase letter (Camel case): Google, npm, Idiomatic, Node 142 | 143 | Prefer longer, descriptive function names. 144 | ```js 145 | function veryLongOperationName 146 | function short().. 147 | ``` 148 | Use vocabulary like is, set, get: 149 | ```js 150 | function isReady() 151 | function setName() 152 | function getName() 153 | ``` 154 | No expressed opinion: jQuery, Crockford 155 | 156 | Arrays 157 | ------ 158 | Use plural forms: Idiomatic 159 | ```js 160 | var documents = []; 161 | ``` 162 | No expressed opinion: Google, jQuery, npm, Node, Crockford 163 | 164 | Objects and classes 165 | ------------------- 166 | 167 | Use Pascal case (every word's first letter is capitalized): Google, npm, Node 168 | ```js 169 | var ThisIsObject = new Date(); 170 | ``` 171 | No expressed opinion: jQuery, Idiomatic, Crockford 172 | 173 | Other 174 | ----- 175 | Use all-lower-hyphen-css-case for multi-word filenames and config keys: npm 176 | 177 | Suggested .jshintrc file 178 | ======================== 179 | [JSHint](http://www.jshint.com/) is a JavaScript syntax and style checker you can use to alert about code style issues. It integrates well into to many commonly used editors and is a nice way to enforce a common style. See JS Hint documentation for all available options: http://www.jshint.com/docs/#options Below we have created a .jshintrc file that follows the recommendations set above in this article. You can place it in the root folder of your project and JSHint-aware code editors will notice it and follow it though all code in your project. 180 | ```json 181 | { 182 | "camelcase" : true, 183 | "indent": 2, 184 | "undef": true, 185 | "quotmark": "single", 186 | "maxlen": 80, 187 | "trailing": true, 188 | "curly": true 189 | } 190 | ``` 191 | In addition to it you should add into your (browser-read) JavaScript files the following header: 192 | ```js 193 | /* jshint browser:true, jquery:true */ 194 | ``` 195 | In your Node.js files you should add: 196 | ```js 197 | /*jshint node:true */ 198 | ``` 199 | In any kind of JavaScript file it is also good to add the declaration: 200 | ```js 201 | 'use strict'; 202 | ``` 203 | This will affect both JSHint and your JavaScript engine, which will become less compliant but run your JavaScript faster. 204 | 205 | Automatically JSHint files before Git commit 206 | If you want to make sure that all of your JS code stays compliant to the style defined in your .jshintrc, you can set the following contents to your .git/hooks/pre-commit file, which is then run each time you try to commit any new of modified files to the project: 207 | ```bash 208 | #!/bin/bash 209 | # Pre-commit Git hook to run JSHint on JavaScript files. 210 | # 211 | # If you absolutely must commit without testing, 212 | # use: git commit --no-verify 213 | 214 | filenames=($(git diff --cached --name-only HEAD)) 215 | 216 | which jshint &> /dev/null 217 | if [ $? -ne 0 ]; 218 | then 219 | echo "error: jshint not found" 220 | echo "install with: sudo npm install -g jshint" 221 | exit 1 222 | fi 223 | 224 | for i in "${filenames[@]}" 225 | do 226 | if [[ $i =~ \.js$ ]]; 227 | then 228 | echo jshint $i 229 | jshint $i 230 | if [ $? -ne 0 ]; 231 | then 232 | exit 1 233 | fi 234 | fi 235 | done 236 | ``` 237 | Happy coding! 238 | 239 | 240 | 241 | License 242 | ======= 243 | 244 | Copyright (C) 2013 Seravo Oy 245 | 246 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 247 | 248 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 249 | 250 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 251 | --------------------------------------------------------------------------------