Style Guide

Conforming to a consistent style is crucial for code clarity. A consistent style makes it easier for others to understand the implementation when reading the source code, and it may prevent bugs from being introduced into the codebase.

Style is very personal, and there is no one "correct" style for all codes. However, in Athena++, all developers should make a best faith effort to conform to the following style guidelines.

C++ files

The most important guidelines to follow when contributing to Athena++ source code are:

• All code should conform to the C++11 standard, and it must compile with g++, icc, and clang++ without warnings (sets of warning flags defined for each compiler in tst/ci/set_warning_cflag.sh). Avoid all language extensions.

• All code must be thoroughly commented. Use // (not /* ... */) for comments. All .cpp files must begin with license boilerplate (as found in, e.g., main.cpp).

• Indent by 2 space characters, maximum line length of 90 characters, do not use tabs for indenting.

• Strongly avoid use of cpp macros to define inline functions. Avoid use of #ifdef...#endif blocks if at all possible.

• Use header (.hpp) files to define classes and function prototypes. Function implementation should be in corresponding source code (.cpp) file. Exceptions may be necessary (e.g. athena_array.hpp).

• File names: all lower case, words separated by underscore, e.g. parameter_input.cpp

• Type names (classes, structs, typedefs, enums, ...): capitalize each word and avoid use of underscores, e.g. InputParameters

• Function names: treat like type names; use capitals for each word and avoid underscores, e.g. MyFunction.

• Variable names: all lower case, words separated by underscore, e.g. iso_csound

• Performance and clarity are the top priorities, with performance being the most important. No feature of C++ shall be used that sacrifices performance compared to an implementation in C. If clarity must be sacrificed for performance, the corresponding code segments must be thoroughly commented.

• No reliance on external libraries (not even Boost, Blitz++, or I/O libraries), except when absolutely necessary (e.g. OpenMP, MPI, FFTW, HDF5).

Here are some Athena++ API-specific recommendations:

• Use il, iu, jl, ju, kl, ku for local limits for loops along the x1, x2, x3 indices, respectively, to avoid confusion with the is, ie, js, je, ks, ke members of the MeshBlock class. The latter refer to the indices of the lower and upper boundaries of the real (non-ghost) zones in each direction. The former may extend into the ghost zones depending on the particular computation or stencil.

For topics not specified in this guide, follow the recommendations of the Google C++ Style Guide. In addition to the above guidelines, the following rules from the Google C++ Style Guide are enforced when committing changes to Athena++ with the Continuous Integration (CI) infrastructure:

• Do not use namespace using-directives. Use using-declarations instead. [build/namespaces] [5]
• You don't need a ; after a } [readability/braces] [4]
• If an else has a brace on one side, it should have it on both [readability/braces] [5]
• { should almost always be at the end of the previous line [whitespace/braces] [4]
• Missing space before else [whitespace/braces] [5]
• No trailing whitespace
• Header order and alphabetize header includes
  • Exclude OpenMP, MPI, FFTW headers
• Header guard style
• Add #include <string> for string [build/include_what_you_use] [4]
• Don't use if/else if without an else clause if it initializes a variable (fall-through)
• Use space before and after inline comment starting characters //

For the most up to date style rules, refer to the CPPLINT.cfg file in the root project directory.

Paraphrasing Google's guide,

The benefit of a style rule must be large enough to justify asking everyone to remember it.

Here is a selection of rules that are explicitly not enforced:

• whitespace/commas
• whitespace/operators (although you should use whitespace between operators!)

Checking C++ style

The Continuous Integration (CI) setup automatically checks changes to master to ensure that the style of C++ files remain consistent.

It uses cpplint.py, a script developed by Google

Python utilities

While Athena++ is a C++ code, Python files serve several important auxiliary functions in the project:

• Configuring the solver with ./configure.py in the root directory
• Regression Testing with scripts in the tst/regression/ folder
• Reading Data Into Python and visualizing with scripts in the vis/ folder

When modifying the .py files in the above locations or adding new Python to the repository, follow PEP 8 (Style Guide for Python Code) and PEP 257 (Docstring Conventions) guidelines. Some of the most important rules (taken directly from PEP) to follow are:

• Use 4 spaces per indentation level. Use spaces, not tabs.
• The Python standard library is conservative and requires limiting lines to 79 characters (and docstrings/comments to 72).
  • Athena++ change: Relaxed to 90 characters to be consistent with above C++ style
• Function names should be lowercase, with words separated by underscores as necessary to improve readability.
• Always surround these binary operators with a single space on either side: assignment (=), augmented assignment (+=, -= etc.), comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not), Booleans (and, or, not).
  • The exception to that is when = is used to set named parameters.
• Blank lines:
  • Surround top-level function and class definitions with two blank lines.
  • Method definitions inside a class are surrounded by a single blank line.

Checking Python style

Under construction.

Miscellaneous files

The Athena++ repository also includes Bash scripts, athinput. input files, Markdown, YAML, and other miscellaneous file formats. No specific style guidelines are enforced for these files, but we recommend that users consult the files in the repository for their style when writing adding new files of that type.