Common code development practices can be extremely useful in multiple developer environments. Particular styles for code components lead to improved readability of the code and can provide important visual cues to other developers.
Much of this recommended practices document is borrowed from the CUBIT mesh generation project, which in turn borrows its recommended practices from other projects. As a result, C++ coding styles are fairly standard across a variety of Sandia software projects in the engineering and computational sciences.
Style guidelines involve the ability to discern at a glance the type and scope of a variable or function.
Class names should be composed of two or more descriptive words, with the first character of each word capitalized, e.g.:
class ClassName;
Class member variables should be composed of two or more descriptive words, with the first character of the second and succeeding words capitalized, e.g.:
double classMemberVariable;
Temporary (i.e. local) variables are lower case, with underscores separating words in a multiple word temporary variable, e.g.:
int temporary_variable;
Constants (i.e. parameters) and enumeration values are upper case, with underscores separating words, e.g.:
const double CONSTANT_VALUE;
Function names are lower case, with underscores separating words, e.g.:
int function_name();
There is no need to distinguish between member and non-member functions by style, as this distinction is usually clear by context. This style convention allows member function names which set and return the value of a similarly-named private member variable, e.g.:
int memberVariable; void member_variable(int a) { // set memberVariable = a; } int member_variable() const { // get return memberVariable; }
In cases where the data to be set or returned is more than a few bytes, it is highly desirable to employ const references to avoid unnecessary copying, e.g.:
void continuous_variables(const RealVector& c_vars) { // set continuousVariables = c_vars; } const RealVector& continuous_variables() const { // get return continuousVariables; }
Note that it is not necessary to always accept the returned data as a const reference. If it is desired to be able change this data, then accepting the result as a new variable will generate a copy, e.g.:
const RealVector& c_vars = model.continuous_variables(); // reference to continuousVariables cannot be changed RealVector c_vars = model.continuous_variables(); // local copy of continuousVariables can be changed
Appearance of typedefs to redefine or alias basic types is isolated to a few header files (data_types.h
, template_defs.h
), so that issues like program precision can be changed by changing a few lines of typedefs rather than many lines of code, e.g.:
typedef double Real;
xemacs
is the preferred source code editor, as it has C++ modes for enhancing readability through color (turn on "Syntax highlighting"). Other helpful features include "Paren highlighting" for matching parentheses and the "New Frame" utility to have more than one window operating on the same set of files (note that this is still the same edit session, so all windows are synchronized with each other). Window width should be set to 80 internal columns, which can be accomplished by manual resizing, or preferably, using the following alias in your shell resource file (e.g., .cshrc):
alias xemacs "xemacs -g 81x63"
where an external width of 81 gives 80 columns internal to the window and the desired height of the window will vary depending on monitor size. This window width imposes a coding standard since you should avoid line wrapping by continuing anything over 80 columns onto the next line.
Indenting increments are 2 spaces per indent and comments are aligned with the code they describe, e.g.:
void abort_handler(int code) { int initialized = 0; MPI_Initialized(&initialized); if (initialized) { // comment aligned to block it describes int size; MPI_Comm_size(MPI_COMM_WORLD, &size); if (size>1) MPI_Abort(MPI_COMM_WORLD, code); else exit(code); } else exit(code); }
Also, the continuation of a long command is indented 2 spaces, e.g.:
const String& iterator_scheduling = problem_db.get_string("strategy.iterator_scheduling");
and similar lines are aligned for readability, e.g.:
cout << "Numerical gradients using " << finiteDiffStepSize*100. << "%" << finiteDiffType << " differences\nto be calculated by the " << methodSource << " finite difference routine." << endl;
Lastly, #ifdef's are not indented (to make use of syntax highlighting in xemacs).
In addition to the style outlined above, the following file naming conventions have been established for the DAKOTA project.
File names for C++ classes should, in general, use the same name as the class defined by the file. Exceptions include:
The type of file is determined by one of the four file name extensions listed below:
.H A class header file ends in the suffix .H. The header file provides the class declaration. This file does not contain code for implementing the methods, except for the case of inline functions. Inline functions are to be placed at the bottom of the file with the keyword inline preceding the function name.
.C A class implementation file ends in the suffix .C. An implementation file contains the definitions of the members of the class.
.h A header file ends in the suffix .h. The header file contains information usually associated with procedures. Defined constants, data structures and function prototypes are typical elements of this file.
Class documentation uses the doxygen tool available from http://www.doxygen.org and employs the JAVA-doc comment style. Brief comments appear in header files next to the attribute or function declaration. Detailed descriptions for functions should appear alongside their implementations (i.e., in the .C files for non-inlined, or in the headers next to the function definition for inlined). Detailed comments for a class or a class attribute must go in the header file as this is the only option.
NOTE: Previous class documentation utilities (class2frame and class2html) used the "//-" comment style and comment blocks such as this:
//- Class: Model //- Description: The model to be iterated by the Iterator. Contains Variables, Interface, and Response objects. //- Owner: Mike Eldred //- Version: $Id: Dev_Recomm_Pract.dox 4549 2007-09-20 18:25:03Z mseldre $
These tools are no longer used, so remaining comment blocks of this type are informational only and will not appear in the documentation generated by doxygen.