Fall-Throughs in Switch Statements

Question
Is falling through in switch statements an acceptable practice?

Answer
Some folks say yes and others say no. I believe it’s perfectly fine in two scenarios:

• When there are no statements to run for the case.
• When a comment is added to say it’s intentional.

Example

switch (someCondition) {
  case "one":
  case "two":
    // Some code here...
    break;
  case "three":
    // Some more code here...
    /* Intentional
     * fall-through
     */
  default:
    // Yet some more code...
}

Indentation for Switch Constructs

Question
What is the recommended way to indent switch statements in JavaScript?

Answer
There are two main styles. The first indents each case statement one level below the switch statement. The second style aligns each case statement at the same indentation level of the switch statement.

Comments
I prefer the first style. See the examples below.

Examples

// First style.
switch (someCondition) {
  case "one":
    // Code here...
    break;
  case "two":
    // Code here...
    break;
  case "three":
    // Code here...
    break;
  default:
  // Code here...
}

// Second style.
switch (someCondition) {
case "one":
  // Code here...
  break;
case "two":
  // Code here...
  break;
case "three":
  // Code here...
  break;
default:
  // Code here...
}

Spacing for Block Statements

Question
What are some JavaScript style recommendations for spacing in block statements?

Answer
The Dojo Style Guide recommends no spaces between the keyword, opening parenthesis, and opening brace. The Google JavaScript Style Guide specifies one space before the opening parenthesis and one space after the closing parenthesis. The jQuery Core Style Guide goes one step further and recommends a space after the opening parenthesis and one before the closing parenthesis.

Comments
My personal preference is the one prescribed in the Google JavaScript Style Guide.

Examples

// Dojo Style Guide recommendation.
if(someCondition){
  doWork();
}

// Google JavaScript Style Guide recommendation.
if (someCondition) {
  doWork();
}

// jQuery Core Style Guide recommendation.
if ( someCondition ) {
  doWork();
}

JavaScript Brace Alignment

Question
How should I align my braces when writing in JavaScript?

Answer
The most common recommendation is to place opening braces on the same line as the start of a code block.

Comments
If you place opening braces on the line following the start of a code block, you run the chance of introducing automatic semicolon insertion errors.

Examples

// Incorrect.
if (someCondition)
{
  doWork();
}
else
{
  doNothing();
}

// Correct.
if (someCondition) {
  doWork();
} else {
  doNothing();
}

Braces with Control Statements

Question
I’m writing an if or for construct and the body contains a single statement. Is it okay if I omit the curly braces?

Answer
No, it’s not best practice. Use braces for all block statements, including:
• if
• for
• while
• do…while
• try…catch…finally

Examples

// Incorrect. Braces are missing.
if (someCondition)
  doWork();

/* Incorrect.
 * Braces are missing.
 * Multiple statements are on a single line.
 */
if (someCondition) doWork();

/* Incorrect.
 * Braces are present, but...
 * Multiple statements are on a single line.
 */
if (someCondition) { doWork(); }

// Correct.
if (someCondition) {
  doWork();
}

JavaScript Documentation Comments

Question
Should I use comments for documentation purposes? If so, what are some recommended practices?

Answer
It’s recommended that you use documentation comments when needed. This is especially true for public-facing code that others may use. A best practice is to implement the comments using the Java Doc-style. In addition, be sure to provide documentation comments for methods, constructors, and objects with documented methods. See the examples below.

Comments
I recommend using JSDoc as a documentation generator.

Examples

/**
Java Doc-style comments for JavaScript.

@method addBlogPost
@param {String subject} The blog's subject. 
**/
function addBlogPost(subject) {
  click(addPostButton);
  typeText(subjectLine, subject);
  click(saveButton);
}

Using Comments for Browser-Specific Hacks

Question
What should I do when I need to write custom, and sometimes wonky code, to overcome specific browser behavior?

Answer
Be sure to include a comment directly before the code in question.

Comments
Adding a note for odd code in these scenarios is important for two reasons. It ensures that no one will unintentionally change the code. It also allows the code’s author to revisit it in the future to see if it’s still needed. Because, as we all know, browser updates occur frequently.

Commenting Code with Potential Errors

Question
What should I do if the code I’m writing goes against standard practice but is intentional?

Answer
Be sure to include a comment so that other well-meaning developers don’t attempt to fix it.

Example

// Note: Assignment in loop is intentional.
while (element && (element = element[axis])) {
  if ((all || element[TAG_NAME]) && (!fn || fn(element))) {
    return element;
  }
}