Code standard

When submitting new code to chombo-discharge, the following guidelines below show be followed.

C++ standard

We are currently at C++14.

Namespace

All code in chombo-discharge is embedded in a namespace ChomboDischarge. Embedding into a namespace is done by including header file CD_NamespaceHeader.H that contain the necessary definitions. This is done by including after any other file includes. In addition, files must include CD_NamespaceFooter.H at the end.

File names

Each file should contain only one class definition, and the file name must be name of the class prepended by CD_. For example, if you are contributing a class MyClass the header files for this class must be named CD_MyClass.H and the implementation file must be named CD_MyClass.cpp. If your code contains templates or inlined functions, these should be defined in files appended by Implem, e.g. CD_MyClassImplem.H.

File headers

Each file shall begin with the following note:

/* chombo-discharge
* Copyright © <Copyright holder 1>
* Copyright © <Copyright holder 2>
* Please refer to Copyright.txt and LICENSE in the chombo-discharge root directory.
*/

where <Copyright holder 1>, <Copyright holder 2>, etc. are replaced by the copyright holder.

This file header shall be followed by a brief Doxygen documentation, containing at least @file, @brief, and @author. In addition, include header guards identical to the filename, replacing dots by underscores. I.e. for a file CD_MyClass.H the header guard shall read

#ifndef CD_MyClass_H
#define CD_MyClass_H

#endif

File inclusions

File inclusions should use the follow standards for C++, Chombo, and chombo-discharge

  1. C++. Use brackets, e.g. #include <memory>.

  2. Chombo. Use brackets, e.g. #include <LevelData.H>.

  3. chombo-discharge. Use brackets and the file name, e.g. #include <CD_FieldSolver.H>.

Example format

Here is a complete example of a header file in chombo-discharge:

/* chombo-discharge
* Copyright © <Copyright holder 1>
* Copyright © <Copyright holder 2>
* Please refer to Copyright.txt and LICENSE in the chombo-discharge root directory.
*/

/*!
  @file   CD_MyClass.H
  @brief  This file contains ...
  @author Author name
*/

#ifndef CD_MyClass_H
#define CD_MyClass_H

// Std includes (e.g.)
#include <memory>

// Chombo includes (e.g.)
#include <LevelData.H>

// Our includes (e.g.)
#include <CD_EBAMRData.H>
#include <CD_NamespaceHeader.H>

/*!
  @brief This class does the following: ....
*/
class MyClass
{
public:

//...
};

#include <CD_NamespaceFooter.H>

#include <CD_MyClassImplem.H> // Inline and template code included at the end.

#endif

Code syntax

We use the following syntax:

  1. Class names, structs, and namespaces should be in Pascal case where the first letter of every word is capitalized. E.g. a class is called MyClass.

  2. Class functions should be in Camel case where the first letter of every word but the first is capitalized. E.g. functions should be named MyClass::myFunction

  3. Variables should use Pascal-case, with the following requirements:

    • Arguments to functions should be prepended by a_. For example MyClass::myFunction(int a_inputVariable).

    • Class members should always be prepended by m_, indicating it is a member of a class. For example MyClass::m_functionMember.

    • Static variables are prepended by s_. For example MyClass::s_staticFunctionMember.

    • Global variables are prepended by //.

Options files

Options files are named using the same convention as class files, e.g. CD_MyClass.options. It is the responsibility of MyClass to parse these variables correctly.

Everything in the options file should be lower-case, with the exception of the class name which should follow the class name syntax. If you need a separator for the variable, use an underscore _. For variables that should be grouped under a common block, one may use a dot . for grouping them. For a class MyClass and options file might look something like

MyClass.input_variable = 1.0
MyClass.bc.x.lo        = dirichlet 1.0

clang-format

We use clang-format for formatting the source code. Before opening a pull request for review, navigate to $DISCHARGE_HOME and format the code using

find Source Physics Geometries Exec \( -name "*.H" -o -name "*.cpp" \) -exec clang-format -i {} +