[fmt01] All indentation is done using space characters (0x20) not literal tabs (0x09), using three spaces per logical tab stop. Set your editor to always save files in this format.
[fmt02] Preprocessor directives and labels used as the target of a goto statement are always placed in the first column, regardless of the current ambient indentation level:
Other constructs are indented as outlined below.
[fmt03] Avoid using source lines longer than 79 characters. Occasional violations of this item are acceptable when the resulting code avoids an awkward line break or is otherwise more readable as a single long line. Very long lines due to deep indentation levels may be a sign that deeply nested code should be refactored out into a separate function.
[fmt04] Logical lines that are longer than 81 characters should be broken at the most logical point and continued on the next line, indented an additional single space past the current indent level, like:
An alternative layout that's taller rather than wider is:
The nice thing about using this tall layout is that it makes it easy to add comments that identify each of the arguments made to a function with a large number of parameters:
[fmt05] Lines containing expressions should be broken as naturally as possible. Where possible, break after a comma:
If that's not appropriate or feasible, break after an operator:
[fmt06] Only use the \ backslash line-continuation mechanism when it's not possible to find a cleaner place to break. As McConnell puts it in Code Complete:
Make the incompleteness of a statement obvious.
Note that we prefer to use the pre-increment ++i as a general habit. It is guaranteed in all languages that use this construct to work identically to the more commonly seen post-increment i++ that dates back to the earliest days of the C language. In C++, however, maintaining this habit prevents possible inefficiencies when looping over an object that exposes an iteratable interface. Consider the likely cost difference between:
Yes, as Knuth said:
We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil.
but one of the benefits of building up habits is that they let us forget things, but still obtain their advantages.
If the body of the while() is empty, make that explicit, as:
[fmt11] Case statements inside a switch statement are indented one tab stop, and the code for each case is at the same indentation level:
An alternative layout to the above follows, which places the body of each case handler in its own scope. Not only is this more attractive visually, it provides an easy way to declare local variables that are restricted to the scope of an individual case:
[fmt12] Switch statements should always have a default case. If the default case should never be executed, place an ASSERT(false); to make sure that this error is caught during debugging and testing.
[fmt35] When intentionally 'falling through' the bottom of a switch case, include the break; inside of comments, along with a comment indicating that this is done intentionally to avoid maintenance programmers from 'correcting' this 'mistake'.
[fmt36] The exception to [fmt35] is when you're falling through an empty case; there's no need to include a commented-out break. Separate the two case labels with a blank line in the source.
Declaring and Initializing Variables
[fmt13] Declare variables as close to the point of first use as possible, rather than in a single big block at the top of the current scope (unless you're programming in C).
[fmt14] Only declare one variable per line of source code -- don't do this:
[fmt15] Avoid leaving variables uninitialized to avoid the possibility of errors resulting from those variables being accessed while filled with garbage.
[fmt16] Matching curly braces should always be aligned in the same column. In general, this means that curly braces should always be on a line by themselves:
[fmt17] All code inside the braces is indented one tab stop (which is affected by using three space characters).
[fmt18] The only exception to the 'braces alone on a line' rule is found when using a do/while loop:
In this construct, placing the closing brace and the while() on the same line make it clear that the while expression is tied to the preceding scope, which would not be otherwise visually obvious.
[fmt19] In general, prefer to use curly braces even in situations where the language does not require their use, such as very simple if/else statements or for loops:
to avoid maintenance problems in the future.
[fmt20] Another case where "unnecessary" braces should be used is when writing an empty while loop:
instead of the form that is more commonly found in the wild:
By prohibiting this common loop format, we can easily check for cases where legal (but wrong) code like:
performs a loop with no-body, then executes the intended body of the loop exactly once. Python programmers can stop chuckling now.
[fmt21] Language keywords are followed by a single space unless they are followed by a semicolon, like break; or return;
[fmt22] There is never a space between a function or method name and its opening parenthesis. Other opening parentheses should be preceded by a space.
[fmt23] Commas are followed by a single space, and are never preceded by a space.
[fmt24] Semicolons are never preceded by a space. If code follows a semicolon on the same line (as in the control structure for a for() loop, the semicolon is followed by a space.
[fmt25] ( and [ are not followed by a space, and ) and ] are not preceded by a space. An exception to this may be made to make grouping more apparent when using deeply nested parentheses:
[fmt26] Binary operators are separated from both operands by a single space.
[fmt27] Unary operators are not separated from their operand.
[fmt28] When declaring pointer variables in C / C++ or reference variables in C++, the * and & operators are attached to the typename, not the identifier, like:
[fmt29] Inside functions, use blank lines judiciously to group lines of code into logical chunks.
[fmt30] Between functions, use blank lines judiciously to visually separate the functions.
[fmt31] Always use hexadecimal constants or literal values when working with bitwise operators:
Explicit is Better Than Implicit
[fmt32] Don't rely on the fact that many operations may silently be coerced by the compiler into boolean values. Always make the comparison explicit:
[fmt33] However, if you are in fact working with real boolean values, there is no need to labor the point -- code like:
is fine -- you don't need to write code like::
Avoiding Unintended Assignments
[fmt34] "Yoda Conditions" -- To avoid a common bug, always place a constant before a variable when performing equivalence testing:
Note that this 'constants come first' rule only applies to equivalence testing, so code like