3 Programming language style guides are important for the long-term maintainability of software. This guide is based on the [Code Conventions for the Java Programming Language](https://java.sun.com/docs/codeconv/) and [Douglas Crockford's Code Conventions for the JavaScript Programming Language](http://javascript.crockford.com/code.html). Modifications have been made due to my personal experience and preferences.
7 Each file has this same basic format:
11 * @fileoverview Description of the file
17 //------------------------------------------------------------------------------
19 //------------------------------------------------------------------------------
21 // require() statements
23 //------------------------------------------------------------------------------
25 //------------------------------------------------------------------------------
27 // private methods/data
29 //------------------------------------------------------------------------------
31 //------------------------------------------------------------------------------
33 // exported objects/methods
39 The `@author` field gives you credit for having created the file.
43 Each indentation level is made up of four spaces. Do not use tabs.
52 Strings should always use double quotes (never single quotes) and should always appear on a single line. Never use a slash to create a new line in a string.
55 var name = "Nicholas";
58 var name = 'Nicholas';
60 // Bad: Wrapping to second line
61 var longString = "Here's the story, of a man \
64 Numbers should be written as decimal integers, e-notation integers, hexadecimal integers or floating-point decimals with at least one digit before and one digit after the decimal point. Never use octal literals.
79 // Bad: Hanging decimal point
82 // Bad: Leading decimal point
85 // Bad: Octal (base 8) is deprecated
88 The special value `null` should be used only in the following situations:
90 1. To initialize a variable that may later be assign an object value.
91 1. To compare against an initialized variable that may or may not have an object value.
92 1. To pass into a function where an object is expected.
93 1. To return from a function where an object is expected.
101 function getPerson() {
103 return new Person("Nicholas");
110 var person = getPerson();
111 if (person !== null){
115 // Bad: Testing against uninitialized variable
121 // Bad: Testing to see if an argument was passed
122 function doSomething(arg1, arg2, arg3, arg4){
128 Never use the special value `undefined`. To see if a variable has been defined, use the `typeof` operator:
131 if (typeof variable == "undefined") {
135 // Bad: Using undefined literal
136 if (variable == undefined) {
142 Operators with two operands must be preceded and followed by a single space to make the expression clear. Operators include assignments and logical operators.
145 var found = (values[i] === item);
148 if (found && (count > 10)) {
153 for (i = 0; i < count; i++) {
157 // Bad: Missing spaces
158 var found = (values[i]===item);
160 // Bad: Missing spaces
161 if (found&&(count>10)) {
165 // Bad: Missing spaces
166 for (i=0; i<count; i++) {
170 ## Parentheses Spacing
172 When parentheses are used, there should be no whitespace immediately after the opening paren or immediately before the closing paren.
175 var found = (values[i] === item);
178 if (found && (count > 10)) {
183 for (i = 0; i < count; i++) {
187 // Bad: Extra space after opening paren
188 var found = ( values[i] === item);
190 // Bad: Extra space before closing paren
191 if (found && (count > 10) ) {
195 // Bad: Extra space around argument
196 for (i = 0; i < count; i++) {
202 Object literals should have the following format:
204 * The opening brace should be on the same line as the containing statement.
205 * Each property-value pair should be indented one level with the first property appearing on the next line after the opening brace.
206 * Each property-value pair should have an unquoted property name, followed by a colon (no space preceding it), followed by the value.
207 * If the value is a function, it should wrap under the property name and should have a blank line both before and after the function.
208 * Additional empty lines may be inserted to group related properties or otherwise improve readability.
209 * The closing brace should be on a separate line.
226 // Bad: Improper indentation
232 // Bad: Missing blank lines around function
243 When an object literal is passed to a function, the opening brace should be on the same line as if the value is a variable. All other formatting rules from above still apply.
251 // Bad: All on one line
252 doSomething({ key1: value1, key2: value2 });
256 Make frequent use of comments to aid others in understanding your code. Use comments when:
258 * Code is difficult to understand.
259 * The code might be mistaken for an error.
260 * Browser-specific code is necessary but not obvious.
261 * Documentation generation is necessary for an object, method, or property (use appropriate documentation comments).
263 ### Single-Line Comments
265 Single-line comments should be used to document one line of code or a group of related lines of code. A single-line comment may be used in three ways:
267 1. On a separate line, describing the code beneath it.
268 1. At the end of a line, describing the code before it.
269 1. On multiple lines, to comment out sections of code.
271 When on a separate line, a single-line comment should be at the same indentation level as the code it describes and be preceded by a single line. Never use multiple single-line comments on consecutive lines, use a multi-line comment instead.
276 // if you made it here, then all security checks passed
280 // Bad: No empty line preceding comment
282 // if you made it here, then all security checks passed
286 // Bad: Wrong indentation
289 // if you made it here, then all security checks passed
293 // Bad: This should be a multi-line comment
294 // This next piece of code is quite difficult, so let me explain.
295 // What you want to do is determine if the condition is true
296 // and only then allow the user in. The condition is calculated
297 // from several different functions and may change during the
298 // lifetime of the session.
300 // if you made it here, then all security checks passed
304 For single-line comments at the end of a line, ensure there is at least one indentation level between the end of the code and the beginning of the comment:
307 var result = something + somethingElse; // somethingElse will never be null
309 // Bad: Not enough space between code and comment
310 var result = something + somethingElse;// somethingElse will never be null
312 The only acceptable time to have multiple single-line comments on successive lines is to comment out large sections of code. Multi-line comments should not be used for this purpose.
317 // thenDoSomethingElse();
320 ### Multi-Line Comments
322 Multi-line comments should be used to document code that requires more explanation. Each multi-line comment should have at least three lines:
324 1. The first line contains only the `/*` comment opening. No further text is allowed on this line.
325 1. The next line(s) have a `*` aligned with the `*` in the first line. Text is allowed on these lines.
326 1. The last line has the `*/` comment opening aligned with the preceding lines. No other text is allowed on this line.
328 The first line of multi-comments should be indented to the same level as the code it describes. Each subsequent line should have the same indentation plus one space (for proper alignment of the `*` characters). Each multi-line comment should be preceded by one empty line.
334 * if you made it here,
335 * then all security checks passed
340 // Bad: No empty line preceding comment
343 * if you made it here,
344 * then all security checks passed
349 // Bad: Missing a space after asterisk
353 *if you made it here,
354 *then all security checks passed
359 // Bad: Wrong indentation
363 * if you made it here,
364 * then all security checks passed
369 // Bad: Don't use multi-line comments for trailing comments
370 var result = something + somethingElse; /*somethingElse will never be null*/
372 ### Comment Annotations
374 Comments may be used to annotate pieces of code with additional information. These annotations take the form of a single word followed by a colon. The acceptable annotations are:
376 * `TODO` - indicates that the code is not yet complete. Information about the next steps should be included.
377 * `HACK` - indicates that the code is using a shortcut. Information about why the hack is being used should be included. This may also indicate that it would be nice to come up with a better way to solve the problem.
378 * `XXX` - indicates that the code is problematic and should be fixed as soon as possible.
379 * `FIXME` - indicates that the code is problematic and should be fixed soon. Less important than `XXX`.
380 * `REVIEW` - indicates that the code needs to be reviewed for potential changes.
382 These annotations may be used with either single-line or multi-line comments and should follow the same formatting rules as the general comment type. Examples:
385 // TODO: I'd like to find a way to make this faster
390 * HACK: Have to do this for IE. I plan on revisiting in
391 * the future when I have more time. This probably should
392 * get replaced before v1.2.
399 // REVIEW: Is there a better way to do this?
404 // Bad: Annotation spacing is incorrect
405 // TODO : I'd like to find a way to make this faster
408 // Bad: Comment should be at the same indentation as code
409 // REVIEW: Is there a better way to do this?
415 ## Variable Declarations
417 All variables should be declared before they are used. Variable declarations should take place at the beginning of a function using a single `var` statement with one variable per line. All lines after the first should be indented one level so the variable names line up. Variables should be initialized when declared if applicable and the equals operator should be at a consistent indentation level. Initialized variables should come first followed by uninitialized variables.
425 // Bad: Improper initialization alignment
431 // Bad: Incorrect indentation
437 // Bad: Multiple declarations on one line
438 var count = 10, name = "Nicholas",
439 found = false, empty;
441 // Bad: Uninitialized variables first
447 // Bad: Multiple var statements
454 Always declare variables. Implied globals should not be used.
456 ## Function Declarations
458 Functions should be declared before they are used. When a function is not a method (not attached to an object) it should be defined using function declaration format (not function expression format nor using the `Function` constructor). There should be no space between the function name and the opening parentheses. There should be one space between the closing parentheses and the right brace. The right brace should be on the same line as the `function` keyword. There should be no space after the opening parentheses or before the closing parentheses. Named arguments should have a space after the comma but not before it. The function body should be indented one level.
461 function doSomething(arg1, arg2) {
465 // Bad: Improper spacing of first line
466 function doSomething (arg1, arg2){
470 // Bad: Function expression
471 var doSomething = function(arg1, arg2) {
475 // Bad: Left brace on wrong line
476 function doSomething(arg1, arg2)
481 // Bad: Using Function constructor
482 var doSomething = new Function("arg1", "arg2", "return arg1 + arg2");
484 Functions declared inside of other functions should be declared immediately after the `var` statement.
498 // code that uses inner()
501 // Bad: Inner function declared before variables
513 // code that uses inner()
516 Anonymous functions may be used for assignment of object methods or as arguments to other functions. There should be no space between the `function` keyword and the opening parentheses.
519 object.method = function() {
523 // Bad: Incorrect spacing
524 object.method = function () {
528 Immediately-invoked functions should surround the entire function call with parentheses.
531 var value = (function() {
540 // Bad: No parentheses around function call
541 var value = function() {
550 // Bad: Improper parentheses placement
551 var value = (function() {
562 Care should be taken to name variables and functions properly. Names should be limited to alphanumeric characters and, in some cases, the underscore character. Do not use the dollar sign (`$`) or back slash (`\`) characters in any names.
564 Variable names should be formatted in camel case with the first letter being lowercase and the first letter of each subsequent word being uppercase. The first word of a variable name should be a noun (not a verb) to avoid confusion with functions. Do not use underscore for variable names.
567 var accountNumber = "8401-1";
569 // Bad: Begins with uppercase letter
570 var AccountNumber = "8401-1";
572 // Bad: Begins with verb
573 var getAccountNumber = "8401-1";
575 // Bad: Uses underscore
576 var account_number = "8401-1";
578 Function names should also be formatted using camel case. The first word of a function name should be a verb (not a noun) to avoid confusion with variables. Do not use underscore for function names.
581 function doSomething() {
585 // Bad: Begins with uppercase letter
586 function DoSomething() {
590 // Bad: Begins with noun
595 // Bad: Uses underscores
596 function do_something() {
600 Constructor functions, those functions used with the `new` operator to create new objects, should be formatted in camel case but must begin with an uppercase letter. Constructor function names should begin with a non-verb because `new` is the action of creating an object instance.
603 function MyObject() {
607 // Bad: Begins with lowercase letter
608 function myObject() {
612 // Bad: Uses underscores
613 function My_Object() {
617 // Bad: Begins with verb
618 function getMyObject() {
622 Variables that act as constants (values that won't be changed) should be formatted using all uppercase letters with words separated by a single underscore.
625 var TOTAL_COUNT = 10;
631 var total_COUNT = 10;
633 Object properties follow the same naming conventions as variables. Object methods follow the same naming conventions as functions. If a property or method is meant to be private, then it should be prefixed with an underscore character.
639 _getCount: function () {
646 Strict mode should be used in all modules, specified below the file overview comment and above everything else:
648 // Bad: Strict mode in functions
649 function doSomething() {
655 // Bad: Strict mode in global scope and redundant strict mode directive in function
656 "use strict"; // This one is good
658 function doSomething() {
659 "use strict"; // This one is bad
664 // Good: Global strict mode
667 function doSomething() {
668 // no "use strict" here
675 When assigning a value to a variable, use parentheses around a right-side expression that contains a comparison.
678 var flag = (i < count);
680 // Bad: Missing parentheses
681 var flag = i < count;
683 ## Equality Operators
685 Use `===` and `!==` instead of `==` and `!=`. This avoids type coercion errors.
688 var same = (a === b);
695 The ternary operator should be used only for assigning values conditionally and never as a shortcut for an `if` statement.
698 var value = condition ? value1 : value2;
700 // Bad: no assignment, should be an if statement
701 condition ? doSomething() : doSomethingElse();
705 ### Simple Statements
707 Each line should contain at most one statement. All simple statements should end with a semicolon (`;`).
713 // Bad: Multiple statements on one line
718 A return statement with a value should not use parentheses unless they make the return value more obvious in some way. Example:
722 return collection.size();
724 return (size > 0 ? size : defaultSize);
726 ### Compound Statements
728 Compound statements are lists of statements enclosed inside of braces.
730 * The enclosed statements should be indented one more level than the compound statement.
731 * The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement.
732 * Braces are used around all statements, even single statements, when they are part of a control structure, such as a `if` or `for` statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces.
733 * The statement beginning keyword, such as `if`, should be followed by one space and the opening brace should be preceded by a space.
737 The `if` class of statements should have the following form:
751 } else if (condition) {
757 It is never permissible to omit the braces in any part of an `if` statement.
764 // Bad: Improper spacing
769 // Bad: Missing braces
773 // Bad: All on one line
774 if (condition) { doSomething(); }
776 // Bad: All on one line without braces
777 if (condition) doSomething();
781 The `for` class of statements should have the following form:
783 for (initialization; condition; update) {
787 for (variable in object) {
791 Variables should not be declared in the initialization section of a `for` statement.
797 for (i=0, len=10; i < len; i++) {
801 // Bad: Variables declared during initialization
802 for (var i=0, len=10; i < len; i++) {
806 // Bad: Variables declared during initialization
807 for (var prop in object) {
811 When using a `for-in` statement, double-check whether or not you need to use `hasOwnProperty()` to filter out object members.
815 The `while` class of statements should have the following form:
823 The `do` class of statements should have the following form:
829 Note the use of a semicolon as the final part of this statement. There should be a space before and after the `while` keyword.
833 The `switch` class of statements should have the following form:
835 switch (expression) {
843 Each `case` is indented one level under the `switch`. Each `case` after the first, including `default`, should be preceded by a single empty line.
845 Each group of statements (except the default) should end with `break`, `return`, `throw`, or a comment indicating fall through.
860 throw new Error("This shouldn't happen.);
863 If a `switch` doesn't have a `default` case, then it should be indicated with a comment.
882 The `try` class of statements should have the following form:
900 Blank lines improve readability by setting off sections of code that are logically related.
902 Two blank lines should always be used in the following circumstances:
904 * Between sections of a source file
905 * Between class and interface definitions
907 One blank line should always be used in the following circumstances:
910 * Between the local variables in a method and its first statement
911 * Before a multi-line or single-line comment
912 * Between logical sections inside a method to improve readability
914 Blank spaces should be used in the following circumstances:
916 * A keyword followed by a parenthesis should be separated by a space.
917 * A blank space should appear after commas in argument lists.
918 * All binary operators except dot (`.`) should be separated from their operands by spaces. Blank spaces should never separate unary operators such as unary minus, increment (`++`), and decrement (`--`) from their operands.
919 * The expressions in a `for` statement should be separated by blank spaces. Blank spaces should only be used after semicolons, not before.
923 * Never use the primitive wrapper types, such as `String`, to create new objects.
924 * Never use `eval()`.
925 * Never use the `with` statement. This statement isn't available in strict mode and likely won't be available in future ECMAScript editions.