Coding Guidelines

These guidelines define code style conventions for the Axom project. Most of the items were taken from the cited references, sometimes with modifications and simplifications; see References and Useful Resources.

The guidelines emphasize code readability, correctness, portability, and interoperability. Agreement on coding style and following common idioms and patterns provides many benefits to a project with multiple developers. A uniform “look and feel” makes it easier to read and understand source code, which increases team productivity and reduces confusion and coding errors when developers work with code they did not write. Also, guidelines facilitate code reviews by enforcing consistency and focusing developers on common concerns. Some of these guidelines are arbitrary, but all are based on practical experience and widely accepted sound practices. For brevity, most guidelines contain little detailed explanation or justification.

Each guideline is qualified by one of three auxiliary verbs: “must”, “should”, or “may” (or “must not”, “should not”, “may not”).

• A “must” item is an absolute requirement.

• A “should” item is a strong recommendation.

• A “may” item is a potentially beneficial stylistic suggestion.

How to apply “should” and “may” items often depends on the particular code situation. It is best to use these in ways that enhance code readability and help reduce user and developer errors.

Important

• Variations in coding style for different Axom components is permitted. However, coding style within each Axom component must be consistent.

• Deviations from these guidelines must be agreed upon by the Axom team.

• When the team agrees to change the guidelines, this guide must be updated.

Contents:

• 1 Changing Existing Code
  • Follow existing code style
  • Only change code from other sources when it makes sense
• 2 Names
  • Good names are clear and meaningful
  • Avoid cryptic names
  • Use terminology consistently
  • Name directories so it’s easy to know what’s in them
  • Follow file extension conventions
  • Associated source and header file names should match
  • File contents should be clear from file name
  • File names should not differ only by case
  • Namespace name format
  • Type name format
  • Function name format
  • Function names should indicate behavior
  • Related functions should have similar names
  • Data member and variable name format
  • Variable names should indicate type
  • Macro and enumeration name format
• 3 Directory Organization
  • Limit scope of directory contents
  • Put files where it’s easy to find them
• 4 Header File Organization
  • All header file contents should be related
  • Include in a header file only what’s needed to compile it
  • Use forward declarations when you can
  • Organize header file contents for easy understanding
  • All function arguments should have names
  • Header file layout details
• 5 Source File Organization
  • Each source file should have an associated header file
  • Header file include order should follow rules for header files
  • Avoid extraneous header file inclusions
  • Function order in source and header files should match
  • Source file layout details
• 6 Scope
  • Use namespaces to avoid name collisions
  • Use namespaces to hide non-API code in header files
  • Use ‘unnamed’ namespace for hiding code in source files
  • Apply the ‘using directive’ carefully
  • Use access qualifiers to control class interfaces
  • Use ‘friend’ and ‘static’ rarely
  • Hide nested classes when possible
  • Limit scope of local variables
• 7 Code Documentation
  • Document only what’s needed
  • Documenting new code vs. existing code
  • Write clear documentation
  • Documentation should be easy to spot
  • General Doxygen usage
    • Brief vs. detailed comments
    • Doxygen comment blocks
    • Doxygen inline comments
  • Copyright and release statement
  • File documentation
    • Brief and detailed comments
  • Type documentation
    • Brief and detailed comments
    • Cross-references and caveats
  • Function documentation
    • Example function documentation
    • Brief and detailed comments
    • Return values
    • Arguments
    • Grouping small functions
    • Header file vs. source file documentation
  • Data member documentation
    • Brief and detailed comments
    • Grouping data members
  • Summary of common Doxygen commands
• 8 Design and Implement for Correctness and Robustness
  • Keep it simple…
  • Avoid global and static data
  • Avoid macros and magic numbers for constants
  • Avoid issues with compiler-generated class methods
    • Rule of three
    • Restrict copying of non-copyable resources
    • Rely on compiler-generated methods when appropriate
    • Functors should always be copyable
  • Understand standard rules for compiler-generated methods
  • Initializing and copying class members
    • Initialize all members at construction
    • Know when to use initialization vs. assignment
    • Use the copy-and-swap idiom
    • Initializing, copying, and inheritance
  • Prefer composition to inheritance
  • Keep inheritance relationships simple
  • Design for/against inheritance
  • Use virtual functions responsibly
  • Inline functions
    • Inline short, simple functions
    • Only inline a class constructor when it makes sense
    • Do not inline virtual methods
  • Function and operator overloading
    • There’s a fine line between clever and…
    • Overload consistently
    • Common operators
  • Function arguments
    • Consistent argument order makes interfaces easier to use
    • Pointer and reference arguments and const
    • Always name function arguments
  • Function return points
  • Proper type usage
  • Templates
  • Use const to enforce correct usage
  • Casts and type conversions
    • Avoid C-style casts, const_cast, and reinterpret_cast
    • Use the explicit qualifier to avoid unwanted conversions
  • Memory management
    • Allocate and deallocate memory in the same scope
    • Use new/delete consistently
• 9 Code Formatting
  • Conditional statements and loops
  • White space and code alignment
    • White space enhances code readability
    • Vertical alignment helps to show scope
    • Break lines where it makes sense
    • Use parentheses for clarity
• 10 Common Code Development Macros, Types, etc.
  • Unused variables
  • Disabling compiler-generated methods
  • Conditionally compiled code
  • Error handling
• 11 Portability, Compilation, and Dependencies
  • Portability
    • Nothing beyond C++11
    • No non-standard language constructs
  • Compilation
    • Avoid conditional compilation
    • The compiler is your friend
  • Minimize dependencies on third-party libraries (TPLs)
• References and Useful Resources