4 The conventions here should be applied to all new code, and with common sense
5 when modifying existing code. For example, renaming a widely used, existing
6 function to follow these conventions may not be justified unless the whole code
9 Currently, this only documents the present state of the code: no particular
10 attempt has been made to consolidate the naming.
15 * C++ source files have a ``.cpp`` extension, C source files ``.c``, and
16 headers for both use ``.h``.
17 * For source file :file:`{file}.c`/:file:`{file}.cpp`, declarations that are
18 visible outside the source file should go into a correspondingly named
19 header: :file:`{file}.h`. Some code may deviate from this rule to improve
20 readability and/or usability of the API, but this should then be clearly
23 There can also be a :file:`{file}-impl.h` file that declares classes or
24 functions that are not accessible outside the module. If the whole file only
25 declares symbols internal to the module, then the :file:`-impl.h` suffix is
28 In most cases, declarations that are not used outside a single source file
29 are in the source file.
30 * Use suffix :file:`-doc.h` for files that contain only Doxygen documentation
31 for some module or such, for cases where there is no natural single header
32 for putting the documentation.
33 * For C++ files, prefer naming the file the same as the (main) class it
34 contains. Currently all file names are all-lowercase, even though class
35 names contain capital letters.
36 It is OK to use commonly known abbreviations, and/or omit the name of the
37 containing directory if that would cause unnecessary repetition (e.g., as a
38 common prefix to every file name in the directory) and the remaining part of
39 the name is unique enough.
40 * Avoid having multiple files with the same name in different places within
41 the same library. In addition to making things harder to find, C++ source
42 files with the same name can cause obscure problems with some compilers.
43 Currently, unit tests are an exception to the rule (there is only one
44 particular compiler that had problems with this, and a workaround is
45 possible if/when that starts to affect more than a few of the test files).
47 .. TODO: Consider usage of underscores vs dashes in file names.
49 Common guidelines for C and C++ code
50 ------------------------------------
52 * Preprocessor macros should be all upper-case. Do not use leading
53 underscores, as all such names are reserved according to the C/C++ standard.
54 * Name include guards like ``GMX_DIRNAME_HEADERNAME_H``.
55 * Avoid abbreviations that are not obvious to a general reader.
56 * If you use acronyms (e.g., PME, DD) in names, follow the Microsoft policy on
57 casing: two letters is uppercase (DD), three or more is lowercase (Pme).
58 If the first letter would be lowercase in the context where it is used
59 (e.g., at the beginning of a function name, or anywhere in a C function
60 name), it is clearest to use all-lowercase acronym.
65 * All function and variable names are lowercase, with underscores as word
66 separators where needed for clarity.
67 * All functions that are part of the public API should start with ``gmx_``.
68 Preferably, other functions should as well.
69 Some parts of the code use a ``_gmx_`` prefix for internal functions, but
70 strictly speaking, these are reserved names, so, e.g., a trailing underscore
72 * Old C code and changes to it can still use the hungarian notation for
73 booleans and enumerated variable names, as well as enum values, where they
74 are prefixed with ``b`` and ``e`` respectively, or you can gradually move
75 to the C++ practice below. Whatever you choose, avoid complex abbreviations.
80 * Use CamelCase for all names. Start types (such as classes, structs, and
81 typedefs) with a capital letter, other names (functions, variables) with a
83 You may use an all-lowercase name with underscores if your class closely
84 resembles an external construct (e.g., a standard library construct) named
86 * C++ interfaces are named with an ``I`` prefix, such as in ICommandLineModule.
87 This keeps interfaces identifiable, without introducing too much clutter
88 (as the interface is typically used quite widely, spelling out
89 ``Interface`` would make many of the names unnecessarily long).
90 * Abstract base classes are typically named with an ``Abstract`` prefix.
91 * Member variables are named with a trailing underscore.
92 * Accessors for a variable ``foo_`` are named ``foo()`` and ``setFoo()``.
93 * Global variables are named with a ``g_`` prefix.
94 * Static class variables are named with a ``s_`` prefix.
95 * Global constants are often named with a ``c_`` prefix.
96 * If the main responsibility of a file is to implement a particular class,
97 then the name of the file should match that class, except for possible
98 abbreviations to avoid repetition in file names (e.g., if all classes within
99 a module start with the module name, omitting or abbreviating the module
100 name is OK). Currently, all source file names are lowercase, but this
101 casing difference should be the only difference.
102 * For new C++ code, avoid using the hungarian notation that is a descendant
103 from the C code (i.e., the practice of using a ``b`` prefix for boolean
104 variables and an ``e`` prefix for enumerated variables and/or values).
105 Instead, make the names long with a good description of what they control,
106 typically including a verb for boolean variables, like ``foundAtom``.
107 * It is a good idea to include the name of the enum type
108 as a base in the name of enum values, e.g., ``HelpOutputFormat_Console``,
109 in particular for settings exposed to other modules.
110 * Prefer to use enumerated types and values instead of booleans as control
111 parameters to functions. It is reasonably easy to understand what the
112 argument ``HelpOutputFormat_Console`` is controling, while it is almost
113 impossible to decipher ``TRUE`` in the same place without checking the
114 documentation for the role of the parameter.
116 The rationale for the trailing underscore and the global/static prefixes is
117 that it is immediately clear whether a variable referenced in a method is local
118 to the function or has wider scope, improving the readability of the code.
123 * Test fixtures (the first parameter to ``TEST``/``TEST_F``) are named with a
125 * Classes meant as base classes for test fixtures (or as names to be typedefed
126 to be fixtures) are named with a ``TestBase`` or ``Fixture`` suffix.
127 * The CTest test is named with CamelCase, ending with ``Tests`` (e.g.,
128 ``OptionsUnitTests``).
129 * The test binary is named with the name of the module and a ``-test`` suffix.