Coding conventions - GRTLCollaboration/GRChombo GitHub Wiki

We hope you appreciate the effort we have made to keep the code consistent and readable. This relies on all contributors adhering to a strict style guide, which is set out below. If you want to contribute code to the repository, it will be judged against these criteria and you will be asked to revise it if they are not met.

Note that we use the Clang Format tool to maintain a uniformly formatted code base. The settings are provided in the .clang-format file in the base directory. For information on how to obtain and use clang-format see Using Clang Format .

General conventions

In general we follow the conventions found in the style guide for C++ at https://google.github.io/styleguide/cppguide.html.

One of our key rules is that variable names should not be abbreviated. Everything should be called something recognisable, even if it takes longer to type.

All code should be commented frequently but concisely. Please provide references to a specific arXiv paper where you use a formula that is not generally known or which has several variants.

Specific additions or differences to the standard C++ conventions

  • We use a tab width of 4 spaces
  • Braces {} should be on their own line for loops and conditionals (enforced by Clang Format)
  • Variable names - underscored lower case e.g. shift_advec_coeff
  • Class names - nouns using camel case e.g. ScalarField
  • Function names - verbs using lower case e.g. compute_rhs()
  • Member variables m and underscore e.g. m_level
  • Function arguments a and underscore e.g. a_level
  • nth derivative is denoted by d + number e.g. d1.chi, d2.chi etc
  • Derivatives indices on tensors are located last, e.g. d2_xy of A_ij will be denoted as d2.A[i][j][x][y].
  • Specify tensor index types with upper case cap, e.g. h_UU is $h^{ij}$. If unmarked, the default is lower e.g. h is $h_{ij}$. (Note - two exceptions to this rule are Gamma / chris.contracted and shift which are both U.)
  • No abbreviations apart from: 
    ptr
int
chris
advec
rhs
deriv
vars
coeff
phys
conf
div
num
Re
Im
  • Zdot = $\dot{Z}$ but Z_dot_stuff = $Z\cdot \mathrm{stuff}$
  • By default the quantities are the conformal ones (e.g. Gamma is $\tilde{\Gamma}^i$), phys = not conformal, conf = explicitly conformal
  • Operators on an object are not underscored
  • Greek vars - the use of capital letters makes a difference, so Pi != pi.
  • User enums c_name. Otherwise caps and underscore - e.g. FILL_GHOST_CELLS

Git[Hub] conventions

Here are some things that you should do when using the code in terms of Git[Hub]:

  • All branch names should be in lower case.

  • Any spaces in branch names should be replaced with underscores.

  • Please use enhancement/your_branch_name for any general code improvements and modifications of existing features, feature/your_branch_name for any new features and simulation/your_branch_name for any edits to the code for the purpose of simulations. bugfix/ISSUE_NUMBER can be used for bug fixes, and should be linked to an issue.

  • When writing commit messages, please try to follow this style guide.

    In particular,

    • Rather than writing one long message using a command such as 
      git commit -m "My really really really long single-line commit message that goes on for far too long"
      do 
      git commit
      which should open you into a text editor where you can separate out the short title of the commit from a more detailed description in the body (this is not always necessary for small changes).

      :information_source: Note The default editor is usually vim but if you prefer a different editor you can change it using the command

      git config --global core.editor "<my preferred text editor command>"
    • The title of your commit message should be
      • Ideally less than 50 characters.
      • Written in the imperative mood i.e. it should complete the sentence "If applied, this commit will ...".
      • Start with a capital letter but omit the full stop.
    • The body of your commit message (if necessary) should
      • Wrapped at 72 characters.
      • Explain what and why you have made the change.
      • Link to any relevant GitHub issues.

  • Rebase your commits to avoid lots of tiny ones! For example a commit that says "forgot a semi-colon" should not exist. The command is

    git rebase -i

  • For small pull requests the policy is to squash the commits into one, but for larger amendments (of more than say 1-2 files) commits should be left intact.