docs/dev-manual/formatting.rst

   1 .. _code-formatting:
   2
   3 Guidelines for code formatting
   4 ==============================
   5
   6 The following list provides the general formatting/indentation rules for
   7 |Gromacs| code (C/C++):
   8
   9 * Basic indentation is four spaces.
  10 * Keep lines at a reasonable length.  There is no hard limit, but use 80
  11   characters as a guideline.  If you end up indenting very deeply,
  12   consider splitting the code into functions.
  13 * Do not use tabs, only spaces.  Most editors can be configured to generate
  14   spaces even when pressing tab.  Tabs (in particular when mixed with spaces)
  15   easily break indentation in contexts where settings are not exactly equal
  16   (e.g., in ``git diff`` output).
  17 * No trailing whitespace.
  18 * Use braces always for delimiting blocks, even when there is only a single
  19   statement in an ``if`` block or similar.
  20 * Put braces on their own lines.  The only exception is short one-line inline
  21   functions in C++ classes, which can be put on a single line.
  22 * Use spaces liberally.
  23 * ``extern "C"`` and ``namespace`` blocks are not indented, but all others
  24   (including ``class`` and ``switch`` bodies) are. Namespace blocks have
  25   to have a closing comment with the name of it.
  26
  27 Additionally:
  28
  29 * All source files and other non-trivial scripts should contain a copyright
  30   header with a predetermined format and license information (check existing
  31   files).  Copyright holder should be "the |Gromacs| development team" for the
  32   years where the code has been in the |Gromacs| source repository, but earlier
  33   years can hold other copyrights.
  34 * Whenever you update a file, you should check that the current year is listed
  35   as a copyright year.
  36
  37 Most of the above guidelines are enforced using uncrustify, an automatic source
  38 code formatting tool.  The copyright guidelines are enforced by a separate
  39 Python script.  See :doc:`uncrustify` for details.  Note that due to the
  40 nature of uncrustify (it only does all-or-nothing formatting), it enforces
  41 several additional formatting rules in addition to those above.
  42
  43 Enforcing a consistent formatting has a few advantages:
  44
  45 * No one needs to manually review code for most of these formatting issues,
  46   and people can focus on content.
  47 * A separate automatic script (see below) can be applied to re-establish the
  48   formatting after refactoring like renaming symbols or changing some
  49   parameters, without needing to manually do it all.
  50
  51 A number of user provided set-ups are available for the correct settings of your
  52 favourite text editor. They are provided for convenience only, and may not
  53 exactly conform to the expectations of uncrustify.
  54
  55 Emacs formatting set-up
  56 -----------------------
  57 Insert the following into your .emacs configuration file::
  58
  59     (defun gromacs-c-mode-common-hook ()
  60     ;; GROMACS customizations for c-mode
  61
  62     (c-set-offset 'substatement-open 0)
  63     (c-set-offset 'innamespace 0)
  64     ;; other customizations can go here
  65
  66     (setq c++-tab-always-indent t)
  67     (setq c-basic-offset 4)                  ;; Default is 2
  68     (setq c-indent-level 4)                  ;; Default is 2
  69     (setq c-file-style "stroustrup")
  70     (setq tab-stop-list '(4 8 12 16 20 24 28 32 36 40 44 48 52 56 60))
  71     (setq tab-width 4)
  72     (setq indent-tabs-mode nil)  ; use tabs if t
  73     )
  74     (add-hook 'c-mode-common-hook 'gromacs-c-mode-common-hook)
  75
  76     (defun gromacs-c++-mode-common-hook ()
  77     ;; GROMACS customizations for c++-moe
  78
  79     (c++-set-offset 'substatement-open 0)
  80     (c++-set-offset 'innamespace 0)
  81     ;; other customizations can go here
  82
  83     (setq c++-tab-always-indent t)
  84     (setq c++-basic-offset 4)                  ;; Default is 2
  85     (setq c++-indent-level 4)                  ;; Default is 2
  86     (setq c++-file-style "stroustrup")
  87
  88     (setq tab-stop-list '(4 8 12 16 20 24 28 32 36 40 44 48 52 56 60))
  89     (setq tab-width 4)
  90     (setq indent-tabs-mode nil)  ; use tabs if t
  91     )
  92
  93     (add-hook 'c++-mode-common-hook 'gromacs-c++-mode-common-hook)
  94
  95 This configuration is based on content from `stackoverflow`_.
  96
  97 .. _stackoverflow: http://stackoverflow.com/questions/663588/emacs-c-mode-incorrect-indentation
  98
  99 Eclipse/cdt formatting set-up
 100 -----------------------------
 101
 102 For correct formatting, please use `this profile`_.
 103
 104 .. _this profile: https://gist.github.com/rolandschulz/74f4fae8985d65f33ff6