Training Systems for the 21st Century (TS21)

This document provides the coding standards for the TS21 software integration and development team. The coding standards in this document cover best practices for making code more readable, testable, and maintainable. Standards need to be reviewed and changed as new circumstances arise in software applications and design philosophy. Standards may be waived with the approval of the lead software engineer and the appropriate accompanying documentation. All violations shall be documented and discussed in code inspections. It is important to realize that these standards apply as long as the Trick environment allows it. Any given version of Trick may require deviations of this standard due to compatibility issues between the C++ language and the constructs that Trick allows the project to use.

1.1 The Importance of Standardization

The primary goal of applying these standards is to enable others to use and maintain your code. It is necessary to put yourself in the perspective of the user looking at your code. Is this person going to find the information that is expected? Will it be clear what algorithms you used, and why you used them? Is your code easily reusable?

1.1.1 Good Points

When a project tries to adhere to common standards a few good things happen:

programmers can go into any code and figure out what's going on
new people can get up to speed quickly
people new to C++ are spared the need to develop a personal style
people new to C++ are spared making common mistakes
people make fewer mistakes in consistent environments
programmers have a common enemy :-)

Programs coded according to a standard are more likely to be:

free of common mistakes
easy to maintain
based on a consistent style
easier to read and understand than code without standards
portable to other architectures
free of common types of errors
maintainable by programmers other than the original author

1.1.2 Discussion

The experience of many projects leads to the conclusion that using coding standards makes the project go smoother. Are standards necessary for success? Of course not. But they help, and we need all the help we can get!

1.2 Interpretation

1.2.1 Conventions

The use of the word "shall" in this document requires that any project using this document must comply with the stated standards. There are no exceptions. Code that does not conform to a "shall"-requirement will not be accepted into a formal release.

The use of the word "should" is intended to allow wiggle room for exceptions to a requirement. Any noncompliance to a "should"-requirement must be based upon sound justification and can be challenged/overturned in peer review and standards compliance audits.

The use of the word "may" designates optional requirements.

1.2.2 Terminology

For the sake of simplicity, the use of the word "compiler" means compiler or translator.

"C++ Coding Standard" refers to this document whereas "C++ ANSI Standard" refers to the standard C++ language definition.

The term "method" means function. Usually, a method is a function that is a member of a class.

1.3 Standards Enforcement

First, any serious concerns about the standard should be brought up and worked out within the group. Maybe the standard is not quite appropriate for your situation. It may have overlooked important issues or maybe someone in power vehemently disagrees with certain issues.

It should be understood by the reader that the standards documented here are necessarily affected by current or future limitations levied by the Trick environment. Those requirements will supersede these standards when conflict occurs. This document will be updated to reflect those requirements as it becomes necessary.

Adherence to this standard is required. Period. Code written in C++ will not be accepted into formal customer releases unless that code conforms to this standard.

1.4 Waiver Process

There may be cases where adherence to some aspect of the standard is not feasible. In those cases, the rationale should be brought to the team leads for discussion. Isolated exceptions should be described briefly in a code comment. Global exceptions may influence changing the standard.

1.5 Reused Code

Code that is developed by other organizations and then reused (integrated) into the TS21 does not need to follow the coding standards listed in this document. Minor updates made to reused code should follow as closely as possible the coding style used by the originators.

2.0 Miscellaneous

2.1 Code Organization

2.1.1 File Names

C++ header files shall^[1] be given the suffix ".hh".
C++ implemtation files shall^[2] be given the suffix ".cpp".
Filenames will be the same as the class name to follow the naming convention specified in Section 3.2.

Justification

Promotes consistency.

2.2 Character Set

Only characters belonging to the American Standard Code for Information Interchange (ASCII) set shall^[7] be used in the code development.

Justification

Unprintable characters can cause strange or hard to find error's and different programs expand tabs to different lengths and can interfere with tool operation and editor viewing.

3.0 Names

3.1 General Rules and Conventions

3.1.1 Uniqueness

Identifiers shall^[8] be unique with their differences being more than:

The presence or absence of underscores.
The interchange of the letter O with the number 0 or the letter D.
The letter I with the number 1 or lower-case letter l.
The letter S with the number 5.
The letter Z with the number 2.

Justification

It is easy to misread code with these characters.

3.1.2 Style

Style shall^[9] be consistent within a file.

3.1.3 Use Meaningful Names

All software projects shall^[10]:

use nouns to name data objects such as classes, structures, and variables.
use verbs to name methods and functions, e.g. calculateError() rather than error().
use meaningful names that represent a variable's or constant's usage. currentDate and lastUpdateDate are much better than date1 and date2.
use meaningful names that represent a method's or function's responsibility. runSimulation() is much better than doIt().
use names that refer to the problem domain rather than to computing aspects, e.g. printerReady rather than printerBitFlag.
use meaningful loop counter names and/or array index names if the loop and/or the scope of the array is longer than a few lines (e.g. score[teamIndex] [eventIndex] rather than score[i][j]).
name a class after what it is. If you can't think of what it is that is a clue you have not thought through the design well enough.
avoid the temptation of bringing the name of the base class into the derived class's name. A class should stand on its own. It doesn't matter what it derives from.

Example

   // Notice how redundant "stack" becomes. 
   //There's no need to use the word "stack" in methods and variables.

   template <Type>

   class Stack {

      public:

              int stackSize();
              void addItemToStack(Type item);

         ...

   }

   Stack myStack;
   myStack.addItemToStack(4);
   int tmp = myStack.stackSize;

3.1.4 Name Length Policy

The use of short, non descriptive variable names (e.g. "i") shall^[11] be limited to cases where the variable has a very short scope and its intended usage is self-evident (e.g. a loop counter).
Single variable names that are not loop counters will be allowed when:

The logic consists of lengthy equations where more descriptive names would detract from the larger view of what the equations are doing. References should be supplied so that the publish equations can be easily identifiable in the source code.
The logic is from well know formulations and follows a convention commonly used in the formulation. For example: y = mx + b

The logic is within a method that is very short and performs a very simple and generic task. For example:

 
   double vMult(double a[3], double b[3]) {

       double c[3];

       c[0] = a[0]*b[0];
       c[1] = a[1]*b[1];
       c[2] = a[2]*b[2];

     return c;
   }

Justification

Intention-revealing names should be used to help readers understand the code.

3.1.5 Use of Suffixes and Prefixes

All variable names, constant/enumeration names, and function/method names shall^[12] :

make consistent use of suffixes and prefixes.
place qualifiers (e.g. Avg, Max) at the end of the name.
use common "opposites" consistently, e.g. Add/Remove, Min/Max, Begin/End, First/Last, etc.
use "is" to prefix methods that return boolean values.

Justification

Consistent use of suffixes and prefixes renders the code easier to comprehend.
Placing qualifiers at the end of the name ensures that the most prominent and descriptive part of the name gets read first.

Examples

If one variable is called

numPoints

then another variable should be called

numEvents

rather than

eventCount

3.1.6 Use of Abbreviations

All upper case abbreviations shall^[13] not be permitted.
Abbreviations shall^[14] use an initial upper case letter followed by all lower case letters.

Justification

Using all uppercase for the base name will give conflicts with the naming conventions above. A variable of this type would have to be named eCLSS or cT which is obviously not very readable. Also, when the abbreviation is embedded with other names, the readability is seriously reduced; the word following the abbreviation does not stand out as it should.

Take for example NetworkABCKey. Notice how the C from ABC and K from key are confused. Some people don't mind this and others just hate it so you'll find different policies in different code so you never know what to call something.

Example

   class FluidOz             // NOT FluidOZ
   class NetworkAbcKey       // NOT NetworkABCKey

3.2 Class Names

All class names shall^[15] use upper case letters for word separators, with lower case for the rest of a word.
The first character in a class name shall^[16] be upper case.
Underscores ('_') shall^[17] not be permitted.

Justification

Of all the different naming strategies most people found this one the best compromise.

Example

   class NameOneTwo
   class Name

3.3 Class Library Names

Libraries in danger of conflicting with other libraries should choose some sort of unique prefix to avoid name conflicts.
It's common for a prefix to be two characters, but a longer length is fine.

Example

A set of X-Windows classes could use Xw as a prefix, so a class name could be:

   class XwMenuBar {
      ...
   }

3.4 Method Names

Method names shall^[18] adhere to the same rule as for class names except that the first letter is to be lower case..

Justification

Common practice in the C++ development community. This is identical to variable names, but functions in C++ are distinguishable from variables by their specific form.

Example

   class XwMenuBar {

      public:

         void      addMenu( void );
         void      addMenuOption( int menuNum );

      ...
   }

3.5 Class Attribute Names

All attribute names shall^[19] use upper case letters for word separators, with lower case for the rest of a word.
The first character in a class name shall^[20] be lower case.
Underscores ('_') shall^[21] not be permitted as word separators.
Prefixing with an "m" for member variable should be used to indicate scope.

Justification

This convention makes variables easy to distinguish from types and effectively resolves potential naming collisions as in the declaration :
```
Line line
```
Attributes should use intention-revealing names to indicate their use.

Example

   class XwMenuBar {

      public:

         void      addMenu();
         void      addMenuOption( int menuNum );

      private:

         Menu      mMenu[maxMenus];
         int       mNumMenus;
         ...
   }

3.6 Method Argument Names

The first character shall^[22] be lower case.
All word beginnings after the first letter shall^[23] be upper case as with class names.

Justification

Within the method body, you will always be able to tell which variables were passed as arguments to the method.
You can use names similar to class names without conflicting with class names.

Example

   class NameOneTwo {

      public:

         int  startYourEngines( Engine someEngine, 
                                Engine anotherEngine);
         ...
   }

3.7 Method Argument Lists

All methods shall^[24] have their argument list ordered like the following: output variables, input/output variables, input variables.

Justification

Promotes usability and consistency of code. Additionally, having the input variables last allows usage of default values.

Example

   class Matrix {

      public:

         void  dotProduct( Vector &result, Vector left, Vector right);

         ...
   }

3.8 Global Constants

Global constants shall^[27] be all caps with '_' separators.
Global constants shall^[28] be unique throughout the system regardless of scope.
All constants and/or conversion factors shall^[29] reside in a common project location.
Constants and/or conversions shall^[30] be reused from the following locations by order of precedence:

Standard C, C++ libs
CxTF Common
Trick
Jeod
Antares (maybe, if easily separable, i.e. standalone .h)
Justification

It's tradition for global constants to be named this way. You must be careful to not conflict with other global #defines and enum labels.
Duplicate declarations of reusable constants and conversion factors should be avoided. Unexpected behavior can result when interfacing components use the same constant defined with different accuracies. Subsystem-specific constants should be kept in a common project location to make them more accessible across the project.
When possible, the constants and conversions need to be reused. Care must also be taken to avoid including libraries that will result in undesired overhead by bring in its own dependent libraries. The overhead and likelihood of duplication can be minimized by using the above order of precedence.

Justification

It's tradition for global constants to named this way. You must be careful to not conflict with other global #defines and enum labels.

Example

    const int A_GLOBAL_CONSTANT = 5;

3.9 Type Names

When possible for types based on native types, you should make a typedef.
Typedef names should use the same naming policy as for a class with the word Type appended.

Justification

Of all the different naming strategies many people found this one to be the best compromise.
Types are things so should use upper case letters. Type is appended to make it clear this is not a class.

Example

   typedef uint16  ModuleType;
   typedef uint32  SystemType;

3.10 Enum Names

Enum names shall^[31] follow the naming convention for type names.
Each enumeration constant (member of an enumerated type) shall^[32] be explicitly assigned a value.

Justification

This is the standard rule for enum labels.

Example

   enum PinStateType {
      PIN_OFF = 0,
      PIN_ON = 1
   }

3.11 Macro Names

Macro names shall^[33] be in all upper case using '_' separators.
Macro function names shall^[34] be prefixed by "TS".

Justification

This makes it very clear that the value is not alterable and in the case of macros, makes it clear that you are using a construct that requires care.

Example

  #define TS_MAX( a, b ) blah
  #define TS_IS_ERR( err ) blah

3.12 C Function Names

In a C++ project there should be very few C functions.
The heading for functions shall^[35] be defined as shown in the example.
For C functions you shall^[36] use the GNU convention of all lower case letters with '_' as the word delimiter.
When "#including" a C header that does not have that wrapper (from an externally developed library, like ANTARES), the header shall^[37] be wrapped in extern "C" { ... }

C functions shall^[38] have header files wrapped with the following:

   #ifdef __cplusplus

   extern "C" {
   #endif
   ...

Justification

These forms of function main shown in the example are explicitly sanctioned by the American National Standards Institute (ANSI)-C standard. Other common forms, such as void main(void), only work on some platforms.
It makes C functions very different from any C++ related names.

3.13 Namespaces

All namespaces names shall^[39] use upper case letters for word separators, with lower case for the rest of a word.
The first character in a namespace shall^[40] be uppercase.
Underscores ('_') shall^[41] not be permitted.

Justification

Of all the different naming strategies most people found this one the best compromise.

Example

  namespace Vendor1 {
      class String { ... };
  }

  namespace Vendor2 {
      class String { ... };
  }

  ...

  using namespace Vendor1;
  using namespace Vendor2;

  Vendor1::String s1;
  Vendor2::String s2;

  ...

4.0 Layout

4.1 Code Indentation Policy

Indentation should be done using at 4 spaces for each level.
Tabs shall^[42] not be permitted.
Indent as many levels as needed, but no more. There are no arbitrary rules as to the maximum indenting level. If the indenting level is more than 4 or 5 levels you may think about factoring out code.

Justification

Tabs aren't used because different word processors handle tabs in different ways. The code should be word processor independent.
Studies have shown that 3-4 spaces results in the best code reading comprehension.
As much as people would like to limit the maximum indentation levels it never seems to work in general. We'll trust that programmers will choose wisely how deep to nest code.

Example

   void func( void ){

       if (something bad) {

          if (another thing bad) {

              while (more input) {
              }
          }
        }
  }

4.2 Braces Policies

4.2.1 Keyword Braces Policies

If-then-else blocks of code shall^[43] adhere to the following layout options:

Option 1:

Opening brace on the line immediately following the last member of the function argument list or conditional test indented to the same level as the control statement.
The closing brace at the end of a function residing in the same column as the opening brace.

     Example:

     if (condition){
     ...
     } 
     else if (condition){
     ...
     }
     else{
     ...
     }

Option 2:
- The opening brace resides on the same line after the last member of the function argument list or conditional test.
- The closing brace resides in the same column as the beginning of the function or control statement without any relative indentation.
```
     Example:

     if (condition) 
     {
     ...
     } 
     else if (condition) 
     {
     ...
     }
     else 
     {
     ...
     }
```

4.2.2 Function Braces Policies

The initial brace and trailing brace will follow the following convention:

Option 1: The initial brace and the trailing brace shall^[44] be both be placed on their own lines.
Option 2: The initial brace shall^[45] be placed at the end of the line after the last member of the function argument list or conditional test.

All control statement braces within a given function shall^[46] follow the same format throughout that function.
All function braces within a given file shall^[47] follow the same format throughout that file.

Justification

Either option is acceptable provided they are used consistently throughout the function/file/class.

Example

   Option 1: 

   void myFunc( void )
   {
   ...
   }

   Option 2:

   void myFunc( void ){
   ...
   }

4.2.3 Class, Structure, and Enumeration Braces Policy

Classes, structures, and enumerations shall^[48] follow the same brace policy as keywords.

Example

   class MyClass{ 

       void myFunc( void )
       {
       ...
       }

   }

   enum EventModeEnum {

     MODE_SINGLE_EVENT = 1,
     MODE_MULTIPLE_EVENTS = 2

   }

4.3 Alignment Policies

Blocks of variable declarations should be aligned.
Blocks of related code, e.g. variable assignments, should be aligned.
Function arguments that must be spread across multiple lines should be aligned (in both function prototypes and function calls).
Keyword arguments that must be spread across multiple lines should be aligned.
Assignment statements that must be spread across multiple lines should be indented after the assignment operator.

Example

   DWord       dWord;
   DWord*      myDWord;
   char*       myChar;
   char        anotherChar;

   dWord        = 0;
   myDWword     = NULL;
   myChar       = NULL;
   anotherChar  = 0;

   if ( ('0' <= myChar && myChar <= '9') || 
        ('a' <= myChar && myChar <= 'z') || 
        ('A' <= myChar && myChar <= 'Z') ) {
   ...
   }

   scale = (someObject[someIndex].maxX() - someObject[someIndex].minX) \ (plotWin.maxX() - plotWin.minX());

   void myFunction( double arg1, double arg2, ...double argn ){
   ...
   }

4.4 Comment Policies

4.4.1 Endline Comment Policy

The use of endline comments (i.e. comments appended to the end of a line) shall^[49] be limited to two cases:

Comments to describe function arguments
Comments to describe class or structure members

Endline comments shall^[50] be aligned within a file.
Endline comments shall^[51] begin with '//' and a single space or any style that simultaneously satisfies both with Trick and Doxygen as documented in the best practices.

Justification

Endline comments are not as visible as full-line comments and are easily overlooked while visually scanning the code.
Endline comments within code are difficult to maintain. When lines of code are changed, the code will grow/shrink in column width, and the endline comments must be realigned.
Endline comments used to describe class/structure members and function arguments should not change as often as code comments.
Endline comments that are

Example

   double interpolate( double* xArray,   // Array of x-values
                       double* yArray,   // Array of y-values
                       double  xVal      // Value to interpolate to
                      )
  {
   ...
  }

   class ViewPort {

   public:
      ...

   private:
      int mXorigin;                   // Screen x-coordinate of viewport
      int mYorigin;                   // Screen y-coordinate of viewport
      int mWid;                       // Width of viewport in pixels
      int mHgt;                       // Height of viewport in pixels
      int mDt;                        // (--) Ok for Trick, not seen by doxygen
      int mTolerance;                 /**< (--) Ok for Trick AND doxygen
      ...
  }

4.4.2 Comment Line Policy

The following policies apply to comments within the code, not including comment blocks for source and header files or for functions/methods.

A comment line shall^[52] immediately precede the code that it describes, with no blank line between the comment and the code.
A comment line shall^[53] be indented to the same level of the code that it describes.
A comment line not intended for doxygen capture shall^[54] begin with "//".

Justification

Placing a comment line at the same indentation level as the code which it describes removes all ambiguity regarding what code is described by the comment.
The use of "//" preceding a comment provides a further visual clue that helps separate the code into discrete subtasks.

Example

   void setupWindow( void )
  {
       Coord      x,y,hotx,hoty;
       Dimension  width, height;
       BitMap     user_bitmap;

       // prompt user for environmental settings
       getWindowSettings( x,y,width,height );
       getCursorSettings( hotx,hoty,user_bitmap );

       // set window positions and size
       window.x      = x;
       window.y      = y;
       window.width  = width;
       window.height = height;
       ...

4.4.3 Function/Method Comment Policy

Each class method and standalone function shall^[55] be preceded by a block of comments following the format that follows the Doxygen convention.

To be picked up by doxygen, comments must be in the ".h" or ".hh" file and begin with "///" or the combination of "/**" and end with a closing "*/".

The function declaration shall^[56] immediately precede the comment block with no blank line between the comment and the declaration.
Unimplemented pure virtual functions shall^[57] be commented.
The comment should be constructed to follow the general look and feel as specified on the project wiki located at: https://orion.jsc.nasa.gov/index.php?n=Main.DoxygenGuidelines.

4.4.4 Source File Comment Policy

Each source code file shall^[58] begin with a block trick header. See the Trick reference document in the code repository for examples.

4.4.5 Header File Comment Policy

Each header file shall^[59] begin with a trick header as required by Trick. See the Trick reference document in the code repository for examples.
The LIBRARY DEPENDENCY line shall^[60] only be included if there are dependencies. Unneeded dependencies should be eliminated.

4.4.6 Header File Comment Policy

Each source code file shall^[61] contain a block of comments following the format as specified in the Example. The comment should be constructed to follow the general look and feel as specified on the project wiki located at: https://pmwiki/index.php?n=Main.DoxygenGuidelines. Note that Trick 10 may allow us combine doxygen and trick headers.

4.5 Maximum Characters Per Line

Lines shall^[62] not exceed 180 characters.

Justification

This limit provides plenty of wiggle room to have intention revealing names and adequately comment our code using endline comments.
This limit still allows viewing of code in a single lab monitor.

4.6 If Then Else Structure

Floating point comparisons shall^[63] use the >= or <= operators.
The constant shall^[64] be placed on the left-hand side of an "==" comparison.
If you have else if statements then it is usually a good idea to always have an else block for finding unhandled cases. Maybe put a log message in the else even if there is no corrective action taken.
Comments can go before the "if" and "else if" lines, to describe the condition being checked, and/or after the "if" and "else if" lines, to describe the actions being taken. In both cases the comment shall^[65] adhere to all commenting policies, i.e. should be preceded by a blank line, indented appropriately, etc.

Justification

Floating point comparisons should always be made with the >= and <= operators rather than the equality operators (==, !=) because the underlying representation and precision for floating point values may differ from machine to machine, and may not be exact.
If = is used instead of ==, the error is caught at compile time. Normally the condition is written such as x == 7 with the variable name on the left and the constant on the right. By reversing these so that the constant is on the left and the variable name is on the right as in 7 == x, the programmer who accidentally replaces the == operator with = is protected by the compiler. Use the text editor to search for all occurrences of =, and check that the correct operator is used for each occurrence.

Example

    if (numArrays > 3) {

    } 

    else if (0 == numArrays) {

    ...

    } 

    else {

    ...

    }

4.7 Switch Formatting

All cases shall^[66] be terminated by a break statement unless a fall through comment is included.
The default case shall^[67] always be present and trigger an error if it should not be reached, yet is reached.
If you need to create variables you should put all the code in a block enclosed by braces.

Example

   switch (...) {

      case 1:
         ...
         // FALL THROUGH

      case 2:
         {        
            int v;
            ...
         }
         break;

      default:
         ...
         break;
   }

4.8 While Formatting

Placement of braces shall^[68] follow the same braces policy as switch policy.
All loops shall^[69] be bounded so that only a finite number of iterations is possible.
All loops should be controlled with integer values.
Within the body of a while structure, there shall^[70] be an action provided that eventually causes the condition in the while to become false.

Justification

The error is called an "infinite loop" in which the repetition structure never terminates. Infinite loops are caused when the loop-continuation condition in a while, for, or do/while structure never becomes false. To prevent this, make sure the value of the condition does change somewhere in the header or body of the loop so the condition can eventually become false.

4.9 Statements Per Line

There should be only one statement per line.

4.10 Source File Layout

Every source file shall^[71] have a corresponding header file.
Source files shall^[72] be less than 1000 lines including blank lines and comments.
#include statements should be located in a single block at the head of the file. Block should be divided into, and ordered by, the following categorization:

System headers (C, C++ or TS21-approved extension, e.g. POSIX).
C System Headers shall^[73] be included within an extern "C" code block.
#include statements for project-related header files
Angle brackets (< >) shall^[74] be used for:

Trick headers where absolutely necessary.
TS21 headers that are not a part of this model.
Predefined system libraries.

To the maximum extent feasible, source code files should follow this order:

a source code comment block.
#include statements for standard library header files
#include statements for project-related header files
macro constant definitions
macro function definitions
enumerated constants and other declared constants
declarations/prototypes for global variables and functions imported, e.g. "extern char *getenv( void );"
declarations/prototypes for global variables and functions exported
declarations/prototypes for static variables and functions that are private to this module
inline function definitions
the functions themselves, each with a function comment block

Functions should appear in the following order:

all public methods for the class

constructor(s)
destructor(s)
access function(s)
operator(s)

all protected methods for the class

constructor(s)
destructor(s)
access function(s)
operator(s)

all private methods for the class; this includes methods for any structures and classes that are declared internally to the class

constructor(s)
destructor(s)
access function(s)
operator(s)

all static functions, i.e. functions that are private to this source file

4.11 Header File Layout Policy

Every header file shall^[75] contain a comment header.
Inclusion of a header file shall^[76] not adversely affect source file compilation, memory or resources.
Every header file shall^[77] contain protection against problems caused by multiple inclusions. Do not use #pragma once; it has been obsolete for ten years.

Example

     < comments and blank lines only! >
     #ifndef < ClassName>_EXISTS
     #define < ClassName>_EXISTS
     < file body >
     #endif

To the maximum extent feasible, header files should follow this order:

a header file comment block
#include statements for standard library header files
#include statements for project-related header files.
macro constant definitions
macro function definitions
inline function definitions
enumerated constants and other declared constants
forward declarations of classes
class declarations
declarations for global variables
function prototypes

4.12 Class Layout Policy

The ordering of class contents shall^[78] be public, protected, private.
A blank line shall^[79] precede the "public:", "private:", and "protected:" lines.
Comment lines shall^[80] be used to group the local structures/classes, data members, the "lifecycle" methods, access methods, operations, and operators. These groups are defined as follows:

Local structures/classes: structures and classes that are declared within the class itself
Data members: the attributes of the class.
Lifecycle methods: constructors and destructors.
Access methods: methods that retrieve or set attribute values. This includes "inquiry" methods such as queue.Isfull().
Operations: non-access methods that do the bulk of the class's work.
Operators: unary and binary operators (e.g. "+") that are overloaded by this class.

Within each of the three sections (i.e. public, private, and protected), the order of groupings should be: local structures/classes, data members, lifecycle methods, access methods, operations, and operators.

Justification

Programmers using the class need to see the public interface more than the implementation details.

Example

class LinkedList {

   public:

      // Lifecycle
      LinkedList( void );
      ~LinkedList( void );

      // Access Methods
      Ptr getFirst( void );
      Ptr getLast( void );
      Ptr getCurrent( void );
      ...

      // Operations
      void sort( (int *userFct)(Ptr, Ptr) );

   private:

      // Link Structure
      struct Link {
         Link* prev;
         Link* curr;
         Link* next;
      }

      // Data Members
      Link* first;
      Link* last;
      Link* current;
}

5.0 Design Guidelines

5.1 Usage Policy for goto,continue, break and ?:

5.1.1 Use of Goto

Goto statements shall^[81] not be used.

Justification

The dangers of using goto statements are well documented in the literature and it is a widely accepted that the usage of goto's is poor programming practice.

5.1.2 Use of Continue and Break

The use of continue and break statements should be minimized.
Continue and break statements should not be both used within the same loop.

Justification

Continue and break statements are just goto statements in disguise.
Use of these statements make the code harder to understand and to trace.
These statements may inadvertently/unintentionally bypass the test condition
These statements may inadvertently/unintentionally bypass the increment/decrement expression

5.1.3 Use of ?:

The conditional expression operator "?" shall^[82] not be used in statements other than macro definitions

Justification

This operator makes code more difficult to read and maintain.

5.1.4 Keywords to Avoid

The following keywords should be avoided. Care must be taken when using these keywords as better options are often available.

__attribute__
#pragma (including pragma once)
asm
flag
mutable
register
struct
typedef (exception for when defining a function pointer or native types (see 3.9)
union
using
volatile

Justification

These keywords make code more difficult to understand and maintain. All 'structs' and 'typedefs' should be made into classes.
Exceptions to this rule will be made for communication across sockets.

5.2 Error Return Check Policy

All function/method calls should be checked for an error return when the function/method provides error information.
The system error text should be output for every system function that provides an error message.

5.3 Object Constructor Usage Policy

An object's constructor should not be used to do any work other than initializing variables and/or actions that cannot fail.
An object should use an init() method (or other equivalent method) to complete its construction. The init() should be called after object instatiation.

Justification

Constructors can't return an error. Object instantiators must check an object for errors after construction. This idiom is often forgotten.
Thrown exceptions inside a constructor can leave an object in an inconsistent state.
When an object is a member attribute of another object, the constructors of the containing object's object can get called at different times depending on implementation. Assumptions about available services can be violated by these subtle changes.

Example

   class Noise
   {
     public:

       Noise();
       Noise(std::map curveFitConstants);

       double calculateScaleFactor();
       double getScaleFactor() const;

     private:

       double scaleFactor;
       void init(std::map curveFitConstants) throw ();
       .
       .
       .

   };

   Noise::Noise(map curveFitConstants)
   {
     try
     {
       init(curveFitConstants);
     }
     catch(InitializationException)
     {
       // If the initialization was not done correctly, just call the default constructor that
       // sets up reasonable values.
       Noise();

       //Log that an exception has occurred and corrective action taken.
       send_hs_msg("Initialization exception occurred. Setting to default constructor values.", "Noise Class");
     }
     catch()
     {
       // Catch the exception that occurred for some unknown reason.
       Noise();

       //Log that an exception has occurred and corrective action taken.
       send_hs_msg("Unknown exception occurred in Constructor. Setting to default constructor values.", "Noise Class");
     }

     }

   void Noise::init(std::map curveFitConstants) throw ()
   {

     // Initialize the scale factor to 0, so no noise is the default.
     this->scaleFactor = 0.0;

     this->s = curveFitConstants["s"];

     // Check to see if the element was initialized. If not, throw an exception.
     if(abs(s) < minTolerance )
     {
       throw exception();
     }
     .
     .
     .

5.4 General Exceptions

5.4.1 General Exception Handling

When handling exceptions, software shall^[83] place the more specific catch alternatives prior to the more general alternatives.
Placing catch ( ... ) before other catch blocks would prevent those blocks from ever being executed; if present, catch (...) should always be placed last in the list of handlers following a try block. Placing a catch that catches a base-class object before a catch that catches an object of a class derived from that base class is a logic error. The base class catch will catch all objects of classes derived from that base-class, so the derived-class catch would never be executed. Placing an exception handler with a void * argument type before exception handlers with other pointer types causes a logic error. The void * handler would catch all exceptions of pointer types, so the other handlers would never execute.
All software shall^[84] explicitly catch exceptions thrown from called methods/functions.
A class should throw an exception, rather than a return code, whenever errors occur that are better handled by the caller.
Exceptions thrown shall^[85] be named in descriptive manner to indicate the nature of the exception.

5.4.2 Destructor Exceptions

An object is presumably created to do something. Some of the changes made by an object should persist after an object dies (is destructed) and some changes should not. Take an object implementing a SQL query. If a database field is updated via the SQL object then that change should persist after the SQL objects dies. To do its work the SQL object probably created a database connection and allocated a bunch of memory. When the SQL object dies we want to close the database connection and deallocate the memory, otherwise if a lot of SQL objects are created we will run out of database connections and/or memory.

The logic might look like:

Sql::~Sql()

{

   delete connection;
   delete buffer;

}

Special care must be taken to catch exceptions which may occur during object destruction. Special care must also be taken to fully destruct an object when it throws an exception.

5.5 Make Functions Reentrant

Functions should not keep static variables that prevent a function from being reentrant.

Justification

Functions can declare variables static. Some C library functions in the past, for example, kept a static buffer to use a temporary work area. Problems happen when the function is called one or more times at the same time. This can happen when multiple tasks are used or say from a signal handler. Using the static buffer caused results to overlap and become corrupted.

The moral is make your functions reentrant by not using static variables in a function. Besides, every machine has 128MB of RAM now so we don't worry about buffer space any more :-)

5.6 Usage Policy for Enumerations, Constants, #defines

The use of #defines should be avoided unless it can be justified as necessary.
Constants that represent the allowable discrete values for a variable of a given type should be declared using an enum.
Other constants should be declared using const.
Constants which are only used by a class should be declared as "static const" within the class.

Justification

C++ introduces the "const" specifically to overcome some of the shortfalls of the #define.
Both const and enum are understood by the debugger, and their use enables type checking to be performed.
The use of an enum and an enum-typed variable explicitly limits the variable's allowable values.

Example

   enum EventMode {
     MODE_SINGLE_EVENT = 1,
     MODE_MULTIPLE_EVENTS = 2
   };

   ...
   EventMode currEventMode;
   ...
   if ( MODE_SINGLE_EVENT == currEventMode ) {
      ...
   }

  class Variables {

   public:

      static const int  A_VARIABLE;
      static const int  B_VARIABLE;
      static const int  C_VARIABLE;
      ...
}

5.7 Macro Function Policy

Code syntax shall^[86] not be changed via macro substitution. It makes the program unintelligible to all but the perpetrator.
Inline functions should be considered before the use of a macro. In C++ macros are not needed for code efficiency.

Justification

Inline functions are type safe and scope bound. Whereas a macro is global in scope and not type safe.

Example

   #define  MAX(x,y)       (((x) > (y) ? (x) : (y))        // Get the maximum

The macro above can be replaced for integers with the following inline function with no loss of efficiency:

   inline int max( int x, int y ) {
     return (x > y ? x : y);
}

5.8 Variable Initialization Policy

Variables shall^[87] always be initialized. Always. Every time.

Justification

More problems than you can believe are eventually traced back to a pointer or variable left uninitialized. C++ tends to encourage this by spreading initialization to each constructor. See Idiom for Initializing Objects .

5.9 Idiom for Initializing Objects

All objects should use the initialization strategy documented using the config/init strategy documented on the wiki at the location: CodingBestPractices

5.10 Braces for Conditional Code

In C++, the conditionally executed code for an if statement or a for loop need not be enclosed in braces if the code is only one line. You shall^[88] enclose the code in braces anyway.

Justification

This explicitly identifies the conditionally executed code.
This removes the potential for forgetting to add the braces if the conditionally executed code is later expanded.

Example

   // DON'T DO IT THIS WAY - no braces enclosing "exit" 
   if (-1 == ret_val )
      exit( -1 );

   // DO IT THIS WAY
   if ( -1 == ret_val ) {
      exit( -1 );
   }

   // DO IT THIS WAY
   factorial = 1;
   for (i=1; i<n; i++) {
      factorial = factorial * i;
   }

5.11 Function/Method Length Policy

Functions and methods should limit themselves to 200 lines of code, including blank lines and comments (but not the function/method comment header block).

Justification

The idea is that each function or method represents a technique for achieving a single objective. If the routine is longer than about 70 lines of code, it probably needs to be broken down into subtasks.
Studies have indicated that optimal reading comprehension is achieved when functions are restricted to about a single page.

5.12 Document Null Statements

You shall^[89] always document a null body for a for or while statement so that it is clear that the null body is intentional and not missing code.

Example

   // Find the first nonblank character in the label
   i = 0;
   while (' ' == label[i++] ) {
      // NULL
   }

5.13 Embedded Assignments

You should avoid the use of embedded assignments when possible. In some constructs it is appropriate and conventional, for example:

      while ((c = getchar()) != EOF) {

         // Process the character
         ...
      }

      if ( NULL == (f = fopen("myfile","w")) ) {

         // Print error message and exit
         ...
      }

The ++ and -- operators count as assignment statements and should only be embedded within other statements when the meaning and order of execution is absolutely unambiguous. For example,

      printf( "%d %d\n", ++i, i+2 );

will give different results on different compilers because the order of evaluation is undefined.

5.14 The Law of Demeter

The Law of Demeter states that you should not access an object directly if it is contained within another object. The containing object should provide in its interface the methods required to access the contained object.

Justification

The purpose of this law is to break dependencies so implementations can change without breaking code. If an object wishes to remove one of its contained objects it won't be able to do so because some other object is using it. If instead the service was through an interface the object could change its implementation anytime without ill effect.

Caveat

As for most laws, the Law of Demeter should be ignored in certain cases. If you have a really high level object that contains a lot of subobjects, like a car contains thousands of parts, it can get absurd to created a method in car for every access to a subobject.

Example

   class SunWorkstation {

     public:

        ...
        SoundCard     sound;
        ...

        void          upVolume( int amount ) { sound.Up( amount ); }
        ...

     private:

        ...

        GraphicsCard  graphics;
   }

   SunWorkstation sun;

   sun.upVolume(1);    // DO
   sun.sound.Up(1);    // DON'T !!!

By making SoundCard private, the "DON'T" will not be possible and will satisfy the Law of Demeter.

5.15 Liskov's Substitution Principle (LSP)

Liskov's Substitution Principle (LSP) states that derived types should be completely substitutable for their base types.

Justification

Users of a class should be able to count on similar behavior from all classes that derive from a base class. No special code should be necessary to qualify an object before using it. If you think about it, violating LSP is also violating the Open/Closed principle because the code would have to be modified every time a derived class was added.

Example

  We define a rectangle class:

   class Rectangle
   {

     public:

         void setWidth(double w) {itsWidth=w;}
         void setHeight(double h) {itsHeight=w;}
         double getHeight() const {return itsHeight;}
         double getWidth() const {return itsWidth;}

     private:

        double itsWidth;
        double itsHeight;

  };

   Later, we find that we need a square. A square is a special kind of rectangle where 
   the height and width are equal. We can inherit from the class Rectangle, but override the height 
   and width method so that when we change one, we change the other. Because we inherit from rectangle, 
   we get the other methods from class Square: 

   class Square : public Rectangle

   {

     public:

         void setWidth(double w);
         void setHeight(double h);

   };

   void Square::setWidth(double w)
  {

     Rectangle::setWidth(w);
     Rectangle::setHeight(w);

   }

   void Square::setHeight(double h)
   {

     Rectangle::setHeight(h);
     Rectangle::setWidth(h);

   }

   Now, when someone sets the width of a Square object, its height will 
   change correspondingly. And when someone sets its height, the width will change 
   with it. Thus, the invariants of the Square remain intact. The Square object will 
   remain a mathematically proper square.

   Square s;

   s.setWidth(1); // Fortunately sets the height to 1 too.
   s.setHeight(2); // sets width and heigth to 2, good thing.

  But consider the following function:

   void f(Rectangle& r)
   {

     r.setWidth(32); // calls Rectangle::setWidth

   }

   If we pass a reference to a Square object into this function, the Square object
   will be corrupted because the height won't be changed. This is a violation of LSP
   because we have changed the behavior of the base class in the derived class.

5.16 Open/Closed Principle

The Open/Closed principle states a class should be both open and closed, where:

open means a class has the ability to be extended.
closed means a class is closed for modifications other than extension.

Justification

Once a class has been approved for use, having gone through code reviews, unit tests, and other qualifying procedures, you don't want to change the class very much, just extend it.
The Open/Closed principle is a pitch for stability. A system is extended by adding new code not by changing already working code. Programmers often don't feel comfortable changing old code because it works!
In practice the Open/Closed principle simply means making good use of abstraction and polymorphism. Abstraction is used to factor out common processes and ideas. Inheritance is used to create an interface that must be adhered to by derived classes.

Example

  An example of Open/Closed violation:

   // Open-Close Principle - Bad example

   class GraphicEditor
   {

     public:

         void drawShape(Shape s) {...}
         void drawCircle(Circle r) {...}
         void drawRectangle(Rectangle r) {...}

   };

   class Shape
   {

     protected:

         int mType;

     public:

        int getMType();

   }; 

   class Rectangle : Shape
   {

     public:

         Rectangle() { Shape::mType = 1; }

         void drawRectangle();

   }; 

   class Circle : Shape
  {

     public:

       Circle() { Shape::mType = 2; }

   };

The GraphicEditor class has to be modified for every new shape class that has to be added. There are several disadvantages:

for each new shape added the unit testing of the GraphicEditor should be redone.
when a new type of shape is added the time for adding it will be high since the developer who add it should understand the logic of the GraphicEditor.
adding a new shape might affect the existing functionality in an undesired way, even if the new shape works perfectly.

An example that doesn't violate Open/Close principle:

   // Open-Close Principle - Good example
   class GraphicEditor
   {

     public:

       virtual ~GraphicEditor();
       void drawShape(Shape* s) { s->draw(); }

   };

   class Shape
   {

     protected:

       int mType;

     public:

       int getMType();

       virtual void draw();

   };

   class Rectangle : Shape
   {

     public:

       Rectangle() { Shape::mType = 1; }
       void draw() { ; /*draw the rectangle*/ 

   };

   Rectangle* myRectangle;
   GraphicEditor ge;

   ge.drawShape(myRectangle);

   In the new design draw() is an abstract method used by GraphicEditor for drawing objects, 
   while moving the implementation in the concrete shape objects. Using the Open/Close Principle 
   the problems from the previous design are avoided, because GraphicEditor is not changed when 
   a new shape class is added:

no unit testing required.
no need to understand the source code from GraphicEditor.
since the drawing code is moved to the concrete shape classes, it's a reduced risk to affect old functionality when new functionality is added.

5.17 Operator Overloading Policy

C++ allows the overloading of all kinds of weird operators. Unless you are building a class directly related to math there are very few operators you should override. You shall^[90] only override an operator when the semantics will be clear to users. For instance, overriding the addition and multiplication operators for a Matrix class makes sense.

Justification

Very few people will have the same intuition as you about what a particular operator will do.

5.18 Class Implementation Policy

Each class definition shall^[91] be in its own file where each file is named directly after the class's name:

      ClassName.hh

In general, each class shall^[92] be implemented in one source file:

      ClassName.cpp   // or whatever the extension is: cpp, c++

If the source file gets too large or you want to avoid compiling templates all the time then add additional files named according to the following rule:

      ClassName_section.cpp

section

5.19 Const Policy

C++ provides the const key word to allow passing as parameters objects that cannot change to indicate when a method doesn't modify its object. Using const in all the right places is called "const correctness."

Example

   void foo(std::string& s);
 
   void bar(std::string const& s)
   {
     foo(s);                      // Compile-time Error since s is const
 
     std::string localCopy = s;
     foo(localCopy);              // OK since localCopy is not const
   } 

   Changes that foo() makes are made to the localCopy object that is local to bar(). 
   In particular, no changes will be made to the const parameter that was passed by reference to bar().

5.20 Streams Policy

You should use streams to perform input/output rather than the familiar printf and related 'C' functions.

Justification

Stdio is not type safe, whereas stream IO is type safe.
When you want to dump an object to a stream there is a standard way of doing it: with the << operator. This is not true of objects and stdio.
One of the more advanced reasons for using streams is that once an object can dump itself to a stream it can dump itself to any stream. One stream may go to the screen, but another stream may be a serial port or network connection.

5.21 Function/Method Argument Policy

Functions and methods, excluding constructors and initialize methods, shall^[93] use no more than six (6).
Functions and methods shall^[94] follow the order specified in section 3.7.
Any error or status value returned as a function argument shall^[95] always be the first argument.
Functions and methods that use similar arguments should list them in consistent order.

Justification

If you wish to make a method with some default inputs, these must be at the end of the list.
A function's/method's argument list is its interface to other routines and should be kept as simple as possible. Six arguments is about the maximum for reasonable reading comprehension. If you use more than six argument you should consider creating a structure or class to encapsulate the related information, and just pass the class/structure instance as an argument.

5.22 Accessor Style Policy

Access methods provide access to the physical or logical attributes of an object. Accessing an object's attributes directly as we do for C structures is greatly discouraged in C++. We disallow direct access to attributes to break dependencies, the reason we do most things. Directly accessing an attribute exposes implementation details about the object.

To see why, ask yourself the following questions:

What if the object decided to provide the attribute in a way other than physical containment?
What if it had to do a database lookup for the attribute?
What if a different object now contained the attribute?

An object makes a contract with the user to provide access to a particular attribute; it should not promise those attributes get their values. Accessing a physical attribute makes such a promise. By allowing the value of an attribute to be changed in an unexpected way, code may break.

The approved idiom for accessors is the Get/Set method. They should be used sparingly. Attributes should be changed naturally as a function of the "update" method of the class. Also, constructors should be used to change any independent variables used in your class. When accessors are used, they should use this method:

   class X {

      public:

         // Get the age
         int getAge( void )
         {
            return age;
         }

         // Set the age
         void setAge( int age )
         {
            this->age = age;
         }

      private:
         int age;
   }

When accessors (gets) are returning boolean values, they should begin with "is".

   class Y {

      public:

         // Get the age
         int getAge( void )
         {
            return age;
         }

         // Set the age
         void setAge( int age )
         {
            this->age = age;
         }

         bool isAMinor( )
         {
            bool result = false;
            if (this->age < 18)
            {
                 result = true;
            }
           
            return result;
         }

      private:

         int age;
   }

5.23 Magic Numbers Policy

You should always use constants, enumerators, or #defines rather than "magic numbers".

Justification

A magic number is a bare naked number used in source code. It's "magic" because nobody has a clue what it means, including the author after 3 months. If there was a number change you might have to change that number multiple places within the code rather than just change the constant declaration.

Example

Using magic numbers:

   for (i=0; i<16; i++) {
      Color[i] = allocateColor( i );
   } 
   ... 
   setLineColor( 3 );
   drawLine( x1, y1, x2, y2 );

Replacing magic numbers with constants and enumerations:

   const int MAX_COLORS = 16;

   enum ColorType {
      COLOR_BLACK = 0,
      COLOR_BLUE = 1,
      COLOR_GREEN = 2,
      COLOR_RED = 3,
      ...
      COLOR_WHITE = 10
   };

   for (i=0; i<MAX_COLORS; i++) {
      Color[i] = allocateColor( i );
   }
   ...
   setLineColor( COLOR_RED );
   drawLine( x1, y1, x2, y2 );

5.24 Required Class Elements

Every class should have the following four methods:

constructor(s)
copy constructor(s)

Copy constructors shall^[95] use call-by-reference, and not call-by-value.

virtual destructor
operator =

Justification

C++ will provide a default Copy constructor and "operator =" operator if the developer does not explicitly provide one. Care needs to be taken when using the default Copy constructors and "operator =" as the default Copy constructor and "operator =" will create a "shallow" copy of any contained pointers. These pointers will point to the original object's data. If the copy is destroyed, the data of the original object will be destroyed too. If the developer does not provide his/her own Copy constructor and "operator =" methods, then these methods should be explicitly defined (blank) and made private - to prevent the (mis)use of the defaults provided by the language.
Not providing an overloaded assignment operator and a copy constructor for a class that contains pointer members is a logic error. A copy constructor and overloaded assignment operator are required to avoid surprises when an object is initialized or copied using an object of the same type. Otherwise, during copy or assignment operations, only the address of the pointer member will be copied. This can result in a serious RT error when the original object used for initialization is deleted.
Copy constructors and operator = are necessary in order to avoid the memory corruption that can occur when temporary copies are made of objects of a class containing pointers. This occurs, for instance, when a function returns a reference to an object.
Copy constructor must use call-by-reference not call-by value; otherwise, the copy constructor call results in infinite recursion (a fatal logic error) because, for call-by-value, a copy of the object passed to the copy constructor must be made, which results in the copy constructor being called recursively. Alternately, if the copy constructor simply copied the pointer in the source object to the target objects pointer, then both objects would point to the same dynamically allocated storage.
Classes derived from this class may contain destructors that must be called properly. Once a function is declared virtual, it remains virtual all the way down the inheritance hierarchy from that point even if it is not declared virtual when a class overrides it. When a derived class chooses not to define a virtual function, the derived class simply inherits its immediate base-class virtual function definition. Base classes must use a virtual destructor in order for objects to be deleted without knowledge of the derived class type.

5.25 Virtual Methods

Visibility of virtual methods:
- If intent is to provide generic interface, visibility shall^[96] be made public/protected.
- If intent is to limit use to non-virtual methods defined by base class, visibility shall^[97] be made private.
Virtual method shall^[98] not be overloaded.
If a class has virtual functions, a virtual destructor shall^[99] be provided.
Even though certain functions are implicitly virtual because of a declaration made higher in the class hierarchy, virtual functions shall^[100] be explicitly declared virtual every level of the hierarchy.

Justification

Classes derived from this class may contain destructors that must be called properly. Once a function is declared virtual, it remains virtual all the way down the inheritance hierarchy from that point even if it is not declared virtual when a class overrides it. When a derived class chooses not to define a virtual function, the derived class simply inherits its immediate base-class virtual function definition.

Example

   class Eps {

      public:

         virtual int getId( );
   };

   class Battery: public Eps {

      public:

         virtual int getId( );
   };

5.26 Data Files

All default data files shall^[101] contain a header.
Models shall^[102] be initialized via Trick default data file, not modified data file.

5.27 Interfaces

When using services provided by Commercial off the Shelf (COTS), GOTS, or other modeling frameworks, software shall^[103] use only documented, non-deprecated interfaces.

Justification

While undocumented services may appear to provide beneficial capability, they are typically not supported by the owner, and may change behavior without notice.
Trick reliance is not good for model reuse.

5.28 Templates

If a template is invoked with a user-defined class type, and if that template uses operators (like =, +, <=, etc.) with objects of that class type, then those operators shall^[104] be overloaded.

Justification

Forgetting to overload such operators causes errors because the compiler, of course, still generates calls to the appropriate overloaded operator functions despite the fact that these functions are not present.

Example

   template <class SomeType>

      ClassName& ClassName::operater=(const ClassName& objVar)
      {
         if ( &objVar != this )
         {
         ...

5.29 Null Pointer Checks

If you receive an pointer argument in a public function call, you shall^[105] check it for null before using it.

Justification

Our code needs to be safety checked in order to prevent unexpected behaviour.
For clarity of code and ease of maintainability, you can eliminate the need for null pointer checks by passing by reference instead (const and non-const). It leads to far clearer, more maintainable and more robust code.

Example

Null Pointer Check:

 

   if ( !fan ) {
     CMN_hs_ptr_msg("ECLSS", "fan");
     // Do any necessary cleanup
     return;
   }

Pass By Reference Vs. Pass by Pointer:

  void foo(SomeObject& obj)
  {
    obj.doSomething();
  }


   void foo(SomeObject* obj)
   {
     obj->doSomething();
   }

5.30 Division Safety

All math functions where a division is performed, the denominator shall^[106] be checked for 0 or some small tolerance. There will not be a common function for this, so each developer should handle it for their own needs.

Justification

Our code needs to be safety checked in order to prevent unexpected behaviour.

Example

   if ( myStuff->voltage >= myStuff->minVoltage ) {
     myStuff ->current = myStuff ->power / myStuff ->voltage;
   }
   else {
   ...

5.31 Min/Max Value Checking

Value checks shall^[107] be performed for values that should fall within a min/max boundary.

Justification

Our code needs to be safety checked in order to prevent unexpected behaviour.

Example

   To limit some variable (rh) in a range where MAX_RH & MIN_RH are constants: 

   // limit relative humidity to range between MIN & MAX
   rh = fmin( fmax(rh, MIN_RH), MAX_RH ); 

   To limit a variable (totalMoles) from going to 0: 
   // limit total moles to small number to prevent divide by zero
   totalMoles = fmax( totalMoles, ECLSS_MIN_GAS_PROPERTY ); 
+

+   if ( 1 > initData.numSegments || initData.numSegments > HxFlowPath::MaxSegments) 
+   {
+     ... 
+   }

5.32 Private Data in Trick

Each class shall^[108] use the TS_MAKE_SIM_COMPATIBLE macro. This will allow attributes (i.e., data members) to be declared private/protected and still be visible to Trick.

Justification

Without this macro, Trick will be unable to access the class for memory management or data recording.

Example

   #include "ts_models/plumbing/fluid/PolyFluid.hh"

   ClassName
   {
     TS_MAKE_SIM_COMPATIBLE( ClassName );
    
      ...
   }

5.33 Relative Include Paths

Each file that is #included or included in the TRICK library dependencies with an relative path shall^[109] be specified according to the following rules:
- #includes to files in the same directory, including a test directory including files in the parent directory, can be specified without any path at all
- #includes in ts_models referring to other code in ts_models should be relative to the ts_models directory
- Any other #includes should be specified relative to the top level of the repository

Justification

Keeping a few simple path rules with respect to referencing include files helps make it more clear where a header actually comes from; a local model, a model internal to our project, or a model from an external delivery.

Example

   // In same directory
   #include "Foo.hh"

   // In other ts_models directory
   #include "sim_utilities/hs/TsHsMsg.hh"

   // Top level of repository
   #include "cxtf/models/cmn/misc/include/cxtf_class.hh"

5.34 Namespaces

Using statements shall^[110] not be allowed.

Justification

Hiding the source of the subprogram obscures the design. For example, using namespaces allows the compiler see any library name, even if unqualified, which can create name conflicts. Instead use fully qualified names.

Example

   class Noise
   {
      public:

       Noise(std::map<string, double> curveFitConstants);

         . . .

     private:

       double scaleFactor;
         . . .

       void init(std::map< string, double> curveFitConstants) throw ();

   };

5.35 Inline Functions

Functions/methods shall^[111] only be used when the functions being inlined are trivial. In this context a trivial function is one that
- contains at most 1 conditional (e.g. if, switch)
- takes only parameters which are of built-in or standard data types (e.g. int, double, std::string, ...)
- contain a maximum of 3 statements (i.e. 3 semicolons)

Justification

Inline functions increase compile time and dependency.
Modern compilers inline functions automatically, so there is no need to explicitly specify in most cases. Although placing inline keyword only gives compiler a hint that this function can be optimized by doing in-lining, its ultimately compiler decision to make it inline.
They often require a header file to include other header files where forward declarations would have sufficed if the methods were non-inline. These additional header file dependencies increase the likelihood compile time errors.
May improve speed, size, thrashing, cache misses, but may also hurt them.

Example

   class Noise
   {
      public:

       Noise(std::map<string, double> curveFitConstants);

         . . .

       double getScaleFactor() const {
         return this->scaleFactor;
       }

     private:

       double scaleFactor;
         . . .

   };

Change Log

1/30 - corrected variable init in 4.3; replaced "primitive" with "native" in 5.1.4.
1/30 - Added some clarifications on the examples: 3.1.3 - fixed example array syntax 3.1.4 - updated the example 3.5 - Added "m" to the member variables. 3.7 - added "&" to the result argument. 4.4.6 - fixed the doxygen link. 4.11 - fixed typo in 3rd bullet. 5.1.4 - fixed typo on "struct" 5.3 - updated condition to eliminate " == 0.0" conditional. 5.15 - fixed garbled text. 5.16 - fixed typos. 5.22 - updated isAMinor to return true is the age is < 18 5.35 - updated to return attribute of "scaleFactor".
12/15/2011 - Relaxed the line length to 180 characters from 100 characters; added the allowance of '/**' endline comment style to the endline standard.
6/20/2011 - updated 5.25 to clarify virtual destructor wording; removed all cxtf references; fixed grammer in 5.24.
5/25/2011 - Updated inline justification to remove incorrect wording.
5/24/2011 - Updated 5.21 to relax the requirement on the number of variables for constructors and initializers.
5/4/2011 - Minor correction to example 5.22.
3/30/2011 - Corrected the Trick friend macro reference; updated the filename reference in section 2.1.1; removed the bullet in 3.1.1 that prohibits identifiers using case to differentiate thus allowing the case "Valve valve" as a declaration; removed the reference to main functions in 3.12; clarified option 2 of 4.2.2; removed the exclusion of the function/method comments from the allowed total to align it with the RSM output;added a new requirement to cover inline functions.
3/16/2011 - Updated requirement 5.31 to clarify that the requirement is to use limit checking without requiring a specific implementation.
3/3/2011 - do not use #pragma once
2/17/2011 - added prefix "is" to reqt 12; removed reqt for local variable names; updated CXTF references to TS; removed doxygen examples and referenced wiki; removed section on init'ing objects to refer to wiki; removed Trick comment header examples and referred to Trick documentation;
1/27/2011 - 5.3 deleted inaccurate rationale bullet; 5.1.4 added back the keywords that mysteriously disappeared; updated 5.3.2 to include protected; 5.30 now titled division safety;
1/26/2011 - Added the missing "keywords to avoid"; updated 4.11 to allow "pragma once".
1/18/2011 - Updated wording to read "==" comparison for reqt 64; fixed <> symbols in 4.11.
10/25/2010 - Fixed wording of requirement 44 to be comprehensible.
10/5/2010 - Updated to include the final comments in the code striker topic: Coding Standards Followup for Toby.
10/4/2010 - Updated 3/12 to say "prefix" instead of "suffix"; updated 3.1.4 example to say vMult instead of vDot; added the word "shall" back to standard "82"; added C standard namespace;added new null pointer check info.
7/15/2010 - Removed redundant standard for ifndef by deleting section 5.7 and adding the text to section 4.11 and renumbered the sections appropriately. No "shalls" were modified.

Training Systems for the 21st Century (TS21)

C++ Coding Standard

Last Modified: January 30, 2012

Table of Contents

1.0 Introduction

1.1 The Importance of Standardization

1.1.1 Good Points

1.1.2 Discussion

1.2 Interpretation

1.2.1 Conventions

1.2.2 Terminology

1.3 Standards Enforcement

1.4 Waiver Process

1.5 Reused Code

2.0 Miscellaneous

2.1 Code Organization

2.1.1 File Names

Justification

2.2 Character Set

Justification

3.0 Names

3.1 General Rules and Conventions

3.1.1 Uniqueness

Justification

3.1.2 Style

3.1.3 Use Meaningful Names

Example

3.1.4 Name Length Policy

Justification

3.1.5 Use of Suffixes and Prefixes

Justification

Examples

3.1.6 Use of Abbreviations

Justification

Example

3.2 Class Names

Justification

Example

3.3 Class Library Names

Example

3.4 Method Names

Justification

Example

3.5 Class Attribute Names

Justification

Example

3.6 Method Argument Names

Justification

Example

3.7 Method Argument Lists

Justification

Example

3.8 Global Constants

Justification

Example

3.9 Type Names

Justification

Example

3.10 Enum Names

Justification

Example

3.11 Macro Names

Justification

Example

3.12 C Function Names

Justification

3.13 Namespaces

Justification

Example

4.0 Layout

4.1 Code Indentation Policy

Justification

Example

4.2 Braces Policies

4.2.1 Keyword Braces Policies

4.2.2 Function Braces Policies

Justification

Example

4.2.3 Class, Structure, and Enumeration Braces Policy

Example