Thoughts on JavaScript Code Indentation

Indentation style is intended to make the logical structure of a program clear. The prevalent indentation styles for JavaScript do not afford enough flexibility to do this optimally.

Having a consistent indentation style goes a long ways toward making code readable and clear in its communication of intent. To further this end, I would like to propose some indentation styles that I find are more effective in communicating the intent and structure of a body of code. These recommendations are likely to be at odds with many of the JavaScript style recommendations that are popular.

Indenting function bodies

Conventional practice for the indentation of the bodies of functions whose declarations are not at the beginning of a line of code typically state that they should be indented by one tab depth. Consider the following example:

Observe that the body of the anonymous function and the body of the function fibonacci are both indented by one tab space from their declaration lines. This camouflages the visual shape of the function. The visual shape of a function is one of those factors that seems to contribute to our ability to passively or even unconsciously think about the code; all of the languages that opt to use meaningful whitespace such as Python and CoffeeScript recognize this. If we dispense with this conventional recommendation, and indent the body of the function to preserve the visual shape of the function, the result looks like this:

The version of the code shown above is easier to understand at a glance; the structure and visual shape of the functions are not obscured by indentation, but are rather enhanced.

Digression: automatic semicolon insertion in JS

One may wonder, why don’t we just put the entire function declaration on its own line instead of indenting the body of the function so far? This would preserve the visual shape of the function without the unusual indentation…

DO NOT DO THIS. Starting the returned function on a new line will cause the anonymous function to return undefined due to automatic semicolon insertion.

… but it introduces a bug. JavaScript has automatic semicolon insertion, and one of the rules which govern how semicolons are inserted states that a line break following the return keyword triggers a semicolon to be inserted. By having a semicolon inserted, the anonymous function would return undefined, and would completely ignore the function we want it to return.

Multiple single-statement conditionals

The style conventions influenced by Douglas Crockford’s recommendations from JavaScript: the Good Parts state that conditional statements should always use curly braces for consistency, and the contents of the conditional blocks should be indented. Consider the following body of code using common conventions:

(Observe that I did not use a switch statement, per the recommendations of Douglas Crockford.) Now, consider the same code with three style changes:

1. since each conditional statement returns, it is not necessary to use separate them with else. The act of returning in one of these conditionals prevents any subsequent conditional from executing.
2. The statements following each of the first four conditionals is so short that they fit cleanly onto the same line as their conditions.
3. The statements following each of the first four conditionals are indented to the same level to give the visual appearance of a column.

Visually, the result is easier to read and represents the structure of the function more clearly:

The contrarian may contend that the code above obscures the structure of the conditionals. While that would be true if the block of statements following the conditionals were several lines long, as I see it, functions and conditionals that are simple enough and short enough may be fitted onto one line; it is more important that the over-all structure of functions be visually recognizable than to strictly indent every conditional block.

Concluding thoughts

For the sake of facilitating the quick visual recognition of functions, and to reduce the mental burden involved in recognizing the structure of code, it may be helpful to indent code beyond the convention of indenting each nested level merely one tab depth at a time. In particular, keeping the shape of functions visible even when they are declared further into a line of code and forming columns when there is a sequence of short conditionals has proven helpful. Consider adjusting your coding style guides to accomodate these tricks.