5c2b890297d97e3d2e2b92f81b2e89d319aa38b8
[alexxy/gromacs.git] / 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 relative to
11    ``src/`` (the latter case should be rare).
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|-specific headers that are not internal to the including module,
27    included with a path relative to ``src/``.
28 8. In *test* files, headers not internal to the module, but specific to
29    testing code, are in a separate block at this point, paths relative to
30    ``src/``.
31 9. Finally, |Gromacs| headers that are internal to the including module are
32    included using a relative path (but never with a path starting with ``../``;
33    such headers go into group 7 instead).  For test files, this group contains
34    headers that are internal to tests for that module.
35
36 All |Gromacs| headers are included with quotes (``"gromacs/utility/path.h"``),
37 other headers with angle brackets (``<stdio.h>``).  Headers under ``src/external/``
38 are generally included with quotes (whenever the include path is relative to
39 ``src/``, as well as for thread-MPI and TNG), but larger third-party entities are
40 included as if they were provided by the system.  The latter group currently
41 includes gtest/gmock.
42
43 If there are any conditionally included headers (typically, only when some
44 #defines from ``config.h`` are set), these should be included at the end of
45 their respective group.  Note that the automatic checker/sorter script does not
46 act on such headers, nor on comments that are between #include statements; it
47 is up to the author of the code to put the headers in proper order in such
48 cases.  Trailing comments on the same line as #include statements are
49 preserved and do not affect the checker/sorter.
50
51 The includestyle used to differentiate between header files that were declared
52 to be part of the module and not used outside the module, and those that were
53 either not part of a module, used in other modules, or installed.
54 As the possibility of installation has been removed (for now), changes to the
55 previous organization might occur where such installed files were implicitly
56 marked as being used outside of a module even though they were not used within
57 |Gromacs| outside their module.
58
59 As part of the effort to build a proper API, a new scheme of separating between
60 public, library and module functionality in header files is planned.
61
62 The guidelines are enforced by an automatic checker script that can also
63 sort/reformat include statements to follow the guidelines.
64 See :doc:`gmxtree` for details.
65
66 Enforcing a consistent order and style has a few advantages:
67
68 * It makes it easy at a quick glance to find the dependencies of a file,
69   without scanning through a long list of unorganized #includes.
70 * Including the header corresponding to the source file first makes most
71   headers included first in some source file, revealing potential problems
72   where headers would not compile unless some other header would be included
73   first.  With this order, the person working on the header is most likely to
74   see these problems instead of someone else seeing them later when
75   refactoring unrelated code.
76 * Consistent usage of paths in #include directives makes it easy to use
77   ``grep`` to find all uses of a header, as well as all include dependencies
78   between two modules.
79 * An automatic script can be used to re-establish clean code after
80   semi-automatic refactoring like renaming an include file with ``sed``, without
81   causing other unnecessary changes.