StyleGuide

Style Guidance

Work in progress! All things here are true, not everything is here.

In general, we will only specify things here that are NOT covered by clang-format.

Clang Format all of Amanzi and ATS

The Amanzi-ATS development team have agreed on using clang-format to provide a uniform formatting of the codebase. A script and all format files are provided. Download and install clang-format from your favorite package manager, then:

cd $AMANZI_SRC_DIR/src
. ../tools/formatting/clang-format.sh

This should be done by the developer or the maintainer before accepting all Pull Requests! In the future, we hope to make this a part of CI, but it is not currently.

Variable spelling

Note that not all of these are followed in the existing code, and these are not hard and fast rules, but nearly guidelines. Prefer to follow these, and when you don't follow them, realize you are yelling and it had better be important (but don't be afraid to yell if it is important).

• Classes, structs, enums, typedefs, template parameters, and namespaces are named in CamelCase, e.g. State, MeshFunction, SolverNKA
  • These should be nouns
  • When inheriting, prefer to prefix with the base class, e.g. SolverNKA inherits from the abstract base class Solver
  • Underscores may be used to make clear modifiers, e.g. Mesh_Helpers may be used to collect functions that help the Mesh object.
• Enums should be enum classes, and should be named with _kind. E.g. Entity_kind, Parallel_kind, etc.
  • A std::string to_string(Entity_kind) function should be provided in the same namespace as the enum.
  • A Entity_kind createEntityKind(const std::string& name) function should also be provided.
• Functions (member and nonmember) should be spelled in lowerCamelCase(), and should always be a verb, e.g. getMyThing() and doSomethingImportant(). This convention is quite new, and is not followed by most of the code. Prefer to match what is there, unless you are refactoring a big part of the code, then fix it.
• Variables should be named lower case with underscores, e.g. my_mesh or surface_mesh or my_member_variable
• Private/protected variables and functions should include a trailing underscore. E.g. getMyPrivateThing_() or my_mesh_
• Files should almost always be named the same thing as the class they implement.
  • Mesh.hh declares the Mesh class, and Mesh.cc implements that class
  • For templated/header only implementations, Mesh_decl.hh declares the class, Mesh_impl.hh implements the class, and Mesh.hh simply includes both.
  • #pragma once or #ifdef / #define header protections should be used (prefer #pragma once in new code)

Tests

• Tests break many of these rules, and are named in lower case/underscore, e.g. state_dag.cc tests the DAG in the state library.
• Tests should be named based on the library/subcomponent they live in. E.g. the mesh_geometry.cc tests the geometry in the mesh library.