docs/dev-manual/formatting.md

   1 Guidelines for code formatting {#page_devstyle_formatting}
   2 ==============================
   3
   4 The following list provides the general formatting/indentation rules for
   5 \Gromacs code (C/C++):
   6  * Basic indentation is four spaces.
   7  * Keep lines at a reasonable length.  There is no hard limit, but use 80
   8    characters as a guideline.  If you end up indenting very deeply,
   9    consider splitting the code into functions.
  10  * Do not use tabs, only spaces.  Most editors can be configured to generate
  11    spaces even when pressing tab.  Tabs (in particular when mixed with spaces)
  12    easily break indentation in contexts where settings are not exactly equal
  13    (e.g., in `git diff` output).
  14  * No trailing whitespace.
  15  * Use braces always for delimiting blocks, even when there is only a single
  16    statement in an `if` block or similar.
  17  * Put braces on their own lines.  The only exception is short one-line inline
  18    functions in C++ classes, which can be put on a single line.
  19  * Use spaces liberally.
  20  * `extern "C"` and `namespace` blocks are not indented, but all others
  21    (including `class` and `switch` bodies) are.
  22
  23 Additionally:
  24  * All source files and other non-trivial scripts should contain a copyright
  25    header with a predetermined format and license information (check existing
  26    files).  Copyright holder should be "the GROMACS development team" for the
  27    years where the code has been in the \Gromacs source repository, but earlier
  28    years can hold other copyrights.
  29  * Whenever you update a file, you should check that the current year is listed
  30    as a copyright year.
  31
  32 Most of the above guidelines are enforced using uncrustify, an automatic source
  33 code formatting tool.  The copyright guidelines are enforced by a separate
  34 Python script.  See \ref page_dev_uncrustify for details.  Note that due to the
  35 nature of uncrustify (it only does all-or-nothing formatting), it enforces
  36 several additional formatting rules in addition to those above.
  37
  38 Enforcing a consistent formatting has a few advantages:
  39  * No one needs to manually review code for most of these formatting issues,
  40    and people can focus on content.
  41  * A separate automatic script (see below) can be applied to re-establish the
  42    formatting after refactoring like renaming symbols or changing some
  43    parameters, without needing to manually do it all.