docs/dev-manual/naming.rst

   1 Naming conventions
   2 ==================
   3
   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
   7 is getting a rework.
   8
   9 Currently, this only documents the present state of the code: no particular
  10 attempt has been made to consolidate the naming.
  11
  12 Files
  13 -----
  14
  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
  21   documented.
  22
  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
  26   omitted.
  27
  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).
  46
  47 Common guidelines for C and C++ code
  48 ------------------------------------
  49
  50 * Preprocessor macros should be all upper-case.  Do not use leading
  51   underscores, as all such names are reserved according to the C/C++ standard.
  52 * Name include guards like ``GMX_DIRNAME_HEADERNAME_H``.
  53 * Avoid abbreviations that are not obvious to a general reader.
  54 * If you use acronyms (e.g., PME, DD) in names, follow the Microsoft policy on
  55   casing: two letters is uppercase (DD), three or more is lowercase (Pme).
  56   If the first letter would be lowercase in the context where it is used
  57   (e.g., at the beginning of a function name, or anywhere in a C function
  58   name), it is clearest to use all-lowercase acronym.
  59
  60 C code
  61 ------
  62
  63 * All function and variable names are lowercase, with underscores as word
  64   separators where needed for clarity.
  65 * All functions that are part of the public API should start with ``gmx_``.
  66   Preferably, other functions should as well.
  67   Some parts of the code use a ``_gmx_`` prefix for internal functions, but
  68   strictly speaking, these are reserved names, so, e.g., a trailing underscore
  69   would be better.
  70 * Old C code and changes to it can still use the hungarian notation for
  71   booleans and enumerated variable names, as well as enum values, where they
  72   are prefixed with ``b`` and ``e`` respectively, or you can gradually move
  73   to the C++ practice below. Whatever you choose, avoid complex abbreviations.
  74
  75 C++ code
  76 --------
  77
  78 * Use CamelCase for all names.  Start types (such as classes, structs,
  79   typedefs and enum values) with a capital letter, other names (functions,
  80   variables) with a lowercase letter.
  81   You may use an all-lowercase name with underscores if your class closely
  82   resembles an external construct (e.g., a standard library construct) named
  83   that way.
  84 * C++ interfaces are named with an ``I`` prefix, such as in ICommandLineModule.
  85   This keeps interfaces identifiable, without introducing too much clutter
  86   (as the interface is typically used quite widely, spelling out
  87   ``Interface`` would make many of the names unnecessarily long).
  88 * Abstract base classes are typically named with an ``Abstract`` prefix.
  89 * Member variables are named with a trailing underscore.
  90 * Accessors for a variable ``foo_`` are named ``foo()`` and ``setFoo()``.
  91 * Global variables are named with a ``g_`` prefix.
  92 * Global and file-static variables are named with a ``g_`` prefix.
  93 * Static class and function variables are named with an ``s_`` prefix.
  94 * Static ``constexpr`` file, class, or function members are named with a ``sc_`` 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 * Prefer class enums over regular ones, so that unexpected conversions to
 108   int do not happen.
 109 * Name functions to convert class enum values to strings as ``enumValueToString``.
 110 * When using a non-class enum, prefer to include the name of the enumeration type
 111   as a base in the name of enum values, e.g., ``HelpOutputFormat_Console``,
 112   in particular for settings exposed to other modules.
 113 * Prefer to use enumerated types and values instead of booleans as control
 114   parameters to functions. It is reasonably easy to understand what the
 115   argument ``HelpOutputFormat_Console`` is controlling, while it is almost
 116   impossible to decipher ``TRUE`` in the same place without checking the
 117   documentation for the role of the parameter.
 118
 119 The rationale for the trailing underscore and the global/static prefixes is
 120 that it is immediately clear whether a variable referenced in a method is local
 121 to the function or has wider scope, improving the readability of the code.
 122
 123 Code for GPUs
 124 -------------
 125
 126 Rationale: on GPUs, using the right memory space is often performance critical.
 127
 128 * In CUDA device code ``sm_``, ``gm_``, and ``cm_`` prefixes are used for
 129   shared, global and constant memory. The absence of a prefix indicates
 130   register space. Same prefixes are used in OpenCL code, where ``sm_``
 131   indicates local memory and no prefixes are added to variables in private
 132   address space.
 133 * Data transferred to and from host has to live in both CPU and GPU memory
 134   spaces. Therefore it is typical to have a pointer or container (in CUDA), or
 135   memory buffer (in OpenCL) in host memory that has a device-based counterpart.
 136   To easily distinguish these, the variables names for such objects are
 137   prefixed ``h_`` and ``d_`` and have identical names otherwise. Example:
 138   ``h_masses``, and ``d_masses``.
 139 * In all other cases, pointers to host memory are not required to have the
 140   prefix ``h_`` (even in parts of the host code, where both host and device
 141   pointers are present). The device pointers should always have the prefix
 142   ``d_`` or ``gm_``.
 143 * In case GPU kernel arguments are combined into a structure, it is preferred
 144   that all device memory pointers within the structure have the prefix ``d_``
 145   (i.e. ``kernelArgs.d_data`` is preferred to ``d_kernelArgs.data``,
 146   whereas both ``d_kernelArgs.d_data`` and ``kernelArgs.data`` are not
 147   acceptable).
 148 * Note that the same pointer can have the prefix ``d_`` in the host code,
 149   and ``gm_`` in the device code. For example, if ``d_data`` is passed to
 150   the kernel as an argument, it should be aliased to ``gm_data`` in the
 151   kernel arguments list. In case a device pointer is a field of a passed
 152   structure, it can be used directly or aliased to a pointer with ``gm_``
 153   prefix (i.e. ``kernelArgs.d_data`` can be used as is or aliased to
 154   ``gm_data`` inside the kernel).
 155 * Avoid using uninformative names for CUDA warp, thread, block indexes and
 156   their OpenCL analogs (i.e. ``threadIndex`` is preferred to ``i`` or
 157   ``atomIndex``).
 158
 159 Unit tests
 160 ----------
 161
 162 * Test fixtures (the first parameter to ``TEST``/``TEST_F``) are named with a
 163   ``Test`` suffix.
 164 * Classes meant as base classes for test fixtures (or as names to be typedefed
 165   to be fixtures) are named with a ``TestBase`` or ``Fixture`` suffix.
 166 * The CTest test is named with CamelCase, ending with ``Tests`` (e.g.,
 167   ``OptionsUnitTests``).
 168 * The test binary is named with the name of the module and a ``-test`` suffix.