Page History

...

When changing pre-existing code, it is reasonable to adjust it to match these conventions. Exception: If the pre-existing code clearly conforms locally to its own peculiar conventions, it is not worth reformatting the whole thing.

Whitespace

Anchor
Whitespace Whitespace

• Indentation levels are two columns.
• There is no hard line length limit.
• Tabs are not allowed in code. Set your editor accordingly. (Emacs: (setq-default indent-tabs-mode nil).)
• Use braces around substatements. (Relaxable for extremely simple substatements on the same line.)
• Use good taste to break lines and align corresponding tokens on adjacent lines.
• Use spaces around operators, especially comparisons and assignments. (Relaxable for boolean expressions and high-precedence operators in classic math-style formulas.)
• Put spaces on both sides of control flow keywords if, else, for, switch, etc.
• * Use extra parentheses in expressions whenever operator precedence seems doubtful. Always use parentheses in shift/mask expressions (<<, &, |, ~).
• Use more spaces and blank lines between larger constructs, such as classes or function definitions.
• If the surrounding code has any sort of vertical organization, adjust new lines horizontally to be consistent with that organization. (E.g., trailing backslashes on long macro definitions often align.)
• Otherwise, use normal conventions for whitespace in C.
• Try not to change whitespace unless it improves readability or consistency. (Different editors indent differently, and spurious indentation changes will just make integrations more difficult.)

Naming

Anchor
Naming Naming

• Type names and global names are mixed-case (FooBar).
• Local names (fields, variables) and function names are lower-case (foo_bar). (For these, avoid mixing in upper case letters.)
• Constant names in upper-case or mixed-case are tolerated, according to historical necessity.
• Constant names should follow an existing pattern, and must have a distinct appearance from other names in related APIs.
• Class and type names are noun phrases. Consider an "er" suffix for a class that represents an action.
• Getter accessor names are noun phrases, with no "get_" noise word. Boolean getters can also begin with "is_" or "has_".
• Setter accessor names prepend "set_" to the getter name.
• Other method names are verb phrases, as if commands to the receiver.
• Avoid leading underscores (as "_oop") except in cases required above. (Names with leading underscores can cause portability problems.)

Commenting

Anchor
Commenting Commenting

• Clearly comment subtle fixes.
• Clearly comment tricky classes and functions.
• If you have to choose between commenting code and writing wiki content, comment the code. Link from the wiki to the source file if it makes sense.
• As a general rule don't add bug numbers to comments (they would soon overwhelm the code). But if the bug report contains significant information that can't reasonably be added as a comment, then refer to the bug report.
• Personal names are discouraged in the source code, which is a team product.

Macros

Anchor
Macros Macros

• You can almost always use an inline function or class instead of a macro. Use a macro only when you really need it.
• Templates may be preferable to multi-line macros. (There may be subtle performance effects with templates on some platforms; revert to macros if absolutely necessary.)
• For build features such as PRODUCT, use #ifdef PRODUCT for multiple-line inclusions or exclusions.
• For short inclusions or exclusions based on build features, use macros like PRODUCT_ONLY and NOT_PRODUCT. But avoid using them with multiple-line arguments, since debuggers do not handle that well.
• Use CATCH, THROW, etc. for HotSpot-specific exception processing.

Grouping

Anchor
Grouping Grouping

• Group related code together, so readers can concentrate on one section of one file.
• Avoid making functions too large, more than a screenful of text; split out chunks of logic into file-local classes or static functions if needed.
• If a class FooBar is going to be used in more than one place, put it a file named fooBar.hpp and fooBar.cpp. If the class is a sidekick to a more important class BazBat, it can go in bazBat.hpp.
• Put a member function FooBar::bang into the same file that defined FooBar, or its associated *.cpp file.

...