Style Guide

Conforming to a consistent style is crucial for code clarity. A clear and consistent style makes it easier for others to understand the implementation, and helps prevent bugs.

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 must compile with g++, icc, and clang. 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). Final implementation should include doxygen annotation of classes and functions.

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

For topics not specified in this guide, follow the recommendations of the Google C++ Style Guide

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 and PEP 257 conventions. Some of the most important guidelines 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).
• 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.