...
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
- 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
- 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.)
- 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
- 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
- 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.
...