docs/dev-manual/includestyle.rst

   1 Guidelines for #include directives
   2 ==================================
   3
   4 The following include order is used in |Gromacs|. An empty line should appear
   5 between each group, and headers within each group sorted alphabetically.
   6
   7 1. Each *source* file should include ``gmxpre.h`` first.
   8 2. If a *source* file has a corresponding header, it should be included next.
   9    If the header is in the same directory as the source, then it is included
  10    without any path (i.e., relative to the source). Otherwise, the canonical
  11    include path of ``libraryname/modulename/header.h`` is used.
  12 3. If the file depends on defines from ``config.h``, that comes next.
  13 4. This is followed by standard C/C++ headers, grouped as follows:
  14
  15    1. Standard C headers (e.g., ``<stdio.h>``)
  16    2. C++ versions of the above (e.g., ``<cstdio>``)
  17    3. Standard C++ headers (e.g., ``<vector>``)
  18
  19    Preferably, only one of the first two groups is present, but this is not
  20    enforced.
  21 5. This is followed by other system headers: platform-specific headers such as
  22    ``<unistd.h>``, as well as external libraries such as
  23    ``<gtest/gtest.h>``.
  24 6. |Gromacs|-specific libraries from ``src/external/``, such as
  25    ``"thread_mpi/threads.h"``.
  26 7. |Gromacs| headers that are not part of the including module.
  27 8. Public |Gromacs| headers that are part of the including module.
  28 9. Finally, |Gromacs| headers that are internal to the including module,
  29    executable, or test target
  30    (typically at the same path as the source file).
  31
  32 All |Gromacs| headers are included with quotes (``"gromacs/utility/path.h"``),
  33 other headers with angle brackets (``<stdio.h>``).  Headers under ``src/external/``
  34 are generally included with quotes (whenever the include path is relative to
  35 ``src/``, as well as for thread-MPI and TNG), but larger third-party entities are
  36 included as if they were provided by the system.  The latter group currently
  37 includes gtest/gmock.
  38
  39 If there are any conditionally included headers (typically, only when some
  40 #defines from ``config.h`` are set), these should be included at the end of
  41 their respective group.  Note that the automatic checker/sorter script does not
  42 act on such headers, nor on comments that are between #include statements; it
  43 is up to the author of the code to put the headers in proper order in such
  44 cases.  Trailing comments on the same line as #include statements are
  45 preserved and do not affect the checker/sorter.
  46
  47 As part of the effort to build a proper API, a new scheme of separating between
  48 public, library and module functionality in header files is planned.
  49 See also :doc:`gmxtree` and
  50 `API restructuring issues <https://gitlab.com/gromacs/gromacs/-/issues?label_name%5B%5D=API+restructuring>`__
  51 for details.
  52
  53 Enforcing a consistent order and style has a few advantages:
  54
  55 * It makes it easy at a quick glance to find the dependencies of a file,
  56   without scanning through a long list of unorganized #includes.
  57 * Including the header corresponding to the source file first makes most
  58   headers included first in some source file, revealing potential problems
  59   where headers would not compile unless some other header would be included
  60   first.  With this order, the person working on the header is most likely to
  61   see these problems instead of someone else seeing them later when
  62   refactoring unrelated code.
  63 * Consistent usage of paths in ``#include`` directives makes it easy to use
  64   ``grep`` to find all uses of a header, as well as all include dependencies
  65   between two modules.
  66 * An automatic script can be used to re-establish clean code after
  67   semi-automatic refactoring like renaming an include file with ``sed``, without
  68   causing other unnecessary changes.