Update naming standards to avoid hungarian notation in C++

Our coding standards still contained lines specifying hungarian
notation for boolean and enumerated types, which is mostly a remnant
from our (really) old C practice. While apps hungarian might provide
some safety (i.e., using one prefix for rows and another for columns),
there is little or no value in systems hungarian where the prefix
is just based on type - in particular when we frequently assign
variables between those types. This recommends us to use long
descriptive names instead, including a verb for boolean variables.
When we eventually get C++11 support we should switch to class enums
to have the compiler to more checking, but that is not yet possible.

Change-Id: I5da9d528a8ef4f23ef67eae3fb72655ea92a9c6a

diff --git a/docs/dev-manual/naming.rst b/docs/dev-manual/naming.rst
index f8bdbc56124fef96ecbee49b619b09c58b78d42b..8a839d26f53d301af591bce0be99ef6762bc4637 100644 (file)
--- a/docs/dev-manual/naming.rst
+++ b/docs/dev-manual/naming.rst
@@ -52,14 +52,6 @@ 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).
@@ -77,6 +69,10 @@ C code
   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.
+* Old C code and changes to it can still use the hungarian notation for
+  booleans and enumerated variable names, as well as enum values, where they
+  are prefixed with ``b`` and ``e`` respectively, or you can gradually move
+  to the C++ practice below. Whatever you choose, avoid complex abbreviations.
 
 C++ code
 --------
@@ -103,6 +99,19 @@ C++ code
   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.
+* For new C++ code, avoid using the hungarian notation that is a descendant
+  from the C code (i.e., the practice of using a ``b`` prefix for boolean
+  variables and an ``e`` prefix for enumerated variables and/or values).
+  Instead, make the names long with a good description of what they control,
+  typically including a verb for boolean variables, like ``foundAtom``.
+* It is a good idea to include the name of the enum type
+  as a base in the name of enum values, e.g., ``HelpOutputFormat_Console``,
+  in particular for settings exposed to other modules.
+* Prefer to use enumerated types and values instead of booleans as control
+  parameters to functions. It is reasonably easy to understand what the
+  argument ``HelpOutputFormat_Console`` is controling, while it is almost
+  impossible to decipher ``TRUE`` in the same place without checking the
+  documentation for the role of the parameter.
 
 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