Add section on naming conventions to dev manual

Move content from the wiki, and expand it a bit.  There have been no
comments to the contents of the wiki page in the time it has existed, so
just convert all discussion items to direct guidelines, describing the
current state of the code.  Add some additional guidelines based on
discussion during review.

Change-Id: I548f907214bb5ca659207aea42b137dd4480cd3d

diff --git a/docs/dev-manual/naming.md b/docs/dev-manual/naming.md
new file mode 100644 (file)
index 0000000..a851cbb
--- /dev/null
+++ b/docs/dev-manual/naming.md
@@ -0,0 +1,102 @@
+Naming conventions {#page_devstyle_naming}
+==================
+
+The conventions here should be applied to all new code, and with common sense
+when modifying existing code.  For example, renaming a widely used, existing
+function to follow these conventions may not be justified unless the whole code
+is getting a rework.
+
+Currently, this only documents the present state of the code: no particular
+attempt has been made to consolidate the naming.
+
+Files
+=====
+
+ * Avoid having multiple files with the same name in different places within
+   the same library.  In addition to making things harder to find, C++ source
+   files with the same name can cause obscure problems with some compilers.
+   Currently, unit tests are an exception to the rule (there is only one
+   particular compiler that had problems with this, and a workaround is
+   possible if/when that starts to affect more than a few of the test files).
+ * For C++ files, prefer naming the file the same as the (main) class it
+   contains.  Currently all file names are all-lowercase, even though class
+   names contain capital letters.
+   It is OK to use commonly known abbreviations, and/or omit the name of the
+   containing directory if that would cause unnecessary repetition (e.g., as a
+   common prefix to every file name in the directory) and the remaining part of
+   the name is unique enough.
+
+TODO: Copy/move relevant content from \ref page_codelayout here, and add
+details.
+
+TODO: Consider usage of underscores vs dashes in file names.
+
+Common guidelines for C and C++ code
+====================================
+
+ * Preprocessor macros should be all upper-case.  Do not use leading
+   underscores, as all such names are reserved according to the C/C++ standard.
+ * Name include guards like `GMX_DIRNAME_HEADERNAME_H`.
+ * Boolean variables are always named with a `b` prefix, followed by a
+   CamelCase name.
+ * Enum values are named with an `e` prefix.  For enum types exposed widely in
+   the codebase, this is followed typically by a part that makes the enum
+   values not conflict with other enums in the same scope.  In C code, this is
+   typically an all-lowercase acronym (e.g., `epbcNONE`); in C++, the same
+   approach may be used, or the name of the enum type is used (e.g.,
+   `eHelpOutputFormat_Console`).
+ * Avoid abbreviations that are not obvious to a general reader.
+ * If you use acronyms (e.g., PME, DD) in names, follow the Microsoft policy on
+   casing: two letters is uppercase (DD), three or more is lowercase (Pme).
+   If the first letter would be lowercase in the context where it is used
+   (e.g., at the beginning of a function name, or anywhere in a C function
+   name), it is clearest to use all-lowercase acronym.
+
+C code
+======
+
+ * All function and variable names are lowercase, with underscores as word
+   separators where needed for clarity.
+ * All functions that are part of the public API should start with `gmx_`.
+   Preferably, other functions should as well.
+   Some parts of the code use a `_gmx_` prefix for internal functions, but
+   strictly speaking, these are reserved names, so, e.g., a trailing underscore
+   would be better.
+
+C++ code
+========
+
+ * Use CamelCase for all names.  Start types (such as classes, structs, and
+   typedefs) with a capital letter, other names (functions, variables) with a
+   lowercase letter.
+   You may use an all-lowercase name with underscores if your class closely
+   resembles an external construct (e.g., a standard library construct) named
+   that way.
+ * C++ interfaces are named with a `Interface` suffix, and abstract base
+   classes with an `Abstract` prefix.
+ * Member variables are named with a trailing underscore.
+ * Accessors for a variable `foo_` are named `foo()` and `setFoo()`.
+ * Global variables are named with a `g_` prefix.
+ * Static class variables are named with a `s_` prefix.
+ * Global constants are often named with a `c_` prefix.
+ * If the main responsibility of a file is to implement a particular class,
+   then the name of the file should match that class, except for possible
+   abbreviations to avoid repetition in file names (e.g., if all classes within
+   a module start with the module name, omitting or abbreviating the module
+   name is OK).  Currently, all source file names are lowercase, but this
+   casing difference should be the only difference.
+
+The rationale for the trailing underscore and the global/static prefixes is
+that it is immediately clear whether a variable referenced in a method is local
+to the function or has wider scope, improving the readability of the code.
+
+Unit tests
+==========
+
+ * Test fixtures (the first parameter to `TEST`/`TEST_F`) are named with a
+   `Test` suffix.
+ * Classes meant as base classes for test fixtures (or as names to be typedefed
+   to be fixtures) are named with a `TestBase` of `Fixture` suffix.
+ * The CTest test is named with CamelCase, ending with `Tests` (e.g.,
+   `OptionsUnitTests`).
+ * The test binary is named with the name of the module and a `-test` suffix.

diff --git a/docs/dev-manual/style.md b/docs/dev-manual/style.md
index bbc6bd19a092525b791df219bbc1de7e905f911c..65c029ccab7e93c75aae216e80ece5c948c625df 100644 (file)
--- a/docs/dev-manual/style.md
+++ b/docs/dev-manual/style.md
@@ -7,6 +7,9 @@ Style guidelines {#page_devstyle}
  - \subpage page_devstyle_includes <br/>
    Guidelines for \#include style (ordering, paths to use, etc.).
 
+ - \subpage page_devstyle_naming <br/>
+   Naming conventions for files and various code constructs.
+
  - [Doxygen guidelines](\ref section_doxygen_guidelines) <br/>
    Guidelines for using Doxygen to document the source code are currently in a
    section on the page on general Doxygen usage.