docs/dev-manual/commitstyle.rst

   1 .. _code-commitstyle:
   2
   3 Guidelines for formatting of git commits
   4 ========================================
   5
   6 While there is no true correct way on how to submit new commits for
   7 code review for |Gromacs|, following these guidelines will help the
   8 review process go smoothly.
   9
  10 General rules for newly submitted code
  11 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  12
  13 New code should follow the other :ref:`style rules<style-guidelines>`
  14 outlined above before submitting. This will make it less likely that your change
  15 will be rejected due to that. If your change modifies some existing
  16 code that does not yet conform to the style, then a preliminary
  17 patch that cleans up the surrounding area is a good idea. We like
  18 to slowly improve the quality while we add or change functionality.
  19
  20 Guidelines for git commit messages
  21 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  22
  23 Commit messages should contain a quick explanation in verb form on what has been
  24 changed or what has been the purpose of the change. If available, the final
  25 part of the message before the ChangeId should be a short section like
  26 **Fixes #redmine-id** to link the change to a possibly previously
  27 posted issue, or **Refs #redmine-id** if the present patch is somehow
  28 related to that work without necessarily fixing the whole issue.
  29
  30 Concerning inline code comments
  31 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  32
  33 New code should be sufficiently commented so that other people will be able to
  34 understand the purpose of the code, and less about the current operation.
  35 Preferably the variable naming and code structure clarify the mechanics, and
  36 comments should only refer to higher-level things, such as choice of algorithm,
  37 or the desire to be consistent with some other part of the code.
  38
  39 For example, the following comment would be insufficient to explain the
  40 (made up example) of iteration over a list of interactions::
  41
  42     /* Code takes each item and iterates over them in a loop
  43      * to store them.
  44      */
  45
  46 A much better example would be explaining why the iteration takes place::
  47
  48     /* We iterate over the items in the list to get
  49      * the specific interaction type for all of them
  50      * and store them in the new data type for future
  51      * use in function foo
  52      */
  53
  54 From the second example, someone debugging might be able to deduce better
  55 if an error observed in *foo* is actually caused by the previous assignment.