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.
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.
- 1 Changing Existing Code
- 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
- 4 Header File Organization
- 5 Source File Organization
- 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
- Copyright and release statement
- File documentation
- Type documentation
- Function documentation
- Data member documentation
- 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
- Understand standard rules for compiler-generated methods
- Initializing and copying class members
- Prefer composition to inheritance
- Keep inheritance relationships simple
- Design for/against inheritance
- Use virtual functions responsibly
- Inline functions
- Function and operator overloading
- Function arguments
- Function return points
- Proper type usage
- Use const to enforce correct usage
- Casts and type conversions
- Memory management
- 9 Code Formatting
- 10 Common Code Development Macros, Types, etc.
- 11 Portability, Compilation, and Dependencies
- References and Useful Resources