Dakota  Version 6.16
Explore and Predict with Confidence
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
Coding Style Guidelines and Conventions
Style Guidelines and Conventions

Introduction

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, yielding some consistency across Sandia projects. While not strict requirements, these guidelines suggest a best-practices starting point for coding in Dakota.

C++/c Style Guidelines

Style guidelines involve the ability to discern at a glance the type and scope of a variable or function.

Class and variable styles

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 styles

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.:

// reference to continuousVariables cannot be changed
const RealVector& c_vars = model.continuous_variables();
// local copy of continuousVariables can be changed
RealVector c_vars = model.continuous_variables();

Miscellaneous

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).

File Naming Conventions

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:

Class Documentation Conventions

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 .cpp 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.

CMake Style Guidelines

Dakota conventions for CMake files, such as CMakeLists.txt, FooConfig.cmake, etc., follow. Our goal is ease of reading, maintenance, and support, similar to the C++ code itself. Current CMake versions and build hints are maintained at the Developer Portal http://dakota.sandia.gov/developer/.

CMake Code Formatting

CMake Variable Naming Conventions

These variable naming conventions are especially important for those that ultimately become preprocessor defines and affect compilation of source files.