C++ Coding Standards

1. Naming Conventions

   Do not rely on upper and lower case differences to yield unique names.

   1. Word separators

      Separate words in identifiers by capitals, not underscores.

   2. Prefixes

      Variable names should be prefixed by Hungarian notation. More than one prefix may apply (e.g. a pointer to an exception object could be named pxPricingException). Regular prefixes include:

      Prefix	Data Type
      a	array
      b	BOOL
      by	unsigned char (BYTE or UCHAR)
      c	char
      C	class
      d	double
      dw	DWORD (unsigned long)
      e	enum variable
      E	enumerated type
      f	float
      h	Windows handle
      i	int or short
      l	long
      m_	class member variable
      n	int
      p	pointer
      s	CString
      sz	zero-terminated char string
      u	unsigned int
      v	void
      w	WORD (unsigned word)
      x	C++ exception object

   3. Names

   Names of enumerated types and classes should begin with an uppercase letter (either E or C, respectively), whereas names of variables and constants should begin with a lowercase letter. Use the Windows standard of starting functions with an upperca

   Names should indicate the meaning of the variables, rather than their type. Names should be descriptive and use complete words. Avoid the use of initial or trailing underscores. Use multiple words – but use them carefully. It can be hard to remember

   Similarly:

   Correct	Incorrect
   szDateDue	szDueDate
   szNameFirst	szFirstName
   eColorRed	eRedColor
   iVolumeMax	iMaxVolume
   bStatusEnabled	bEnabledStatus

   Naming variables this way means that related variables tend to sort together, making cross-reference listings more useful.

2. Aesthetics
   1. Indent size

      Use four spaces. Do not use tabs because different editors and printers deal with tabs differently. These parameters can be set in the Tools/Options menu of Visual C++.

   2. Braces

      Braces shall follow an indented block style in which opening and closing braces are each placed on separate line lined up vertically with the control statement. The body of the code within braces is indented by one indent level.

      Example:

          while (iLoopingCount)
          {
              doSomeThing();
          }
      

   3. Line length

      Line length should not exceed eighty characters.

   4. Statements

      Do not use multiple statements per line.

      Example:

          // Incorrect
      
          a = b; c++; d = GetMax();
      
          // Correct
      
          a = b;
          c++;
          d = GetMax();
      

   5. Class definitions

      Put class names against the margin.

      Example:

          WORD
          class::func()
          {
              doSomeThing();
          }
      

   6. Spaces

   Use lots of spaces, except around ‘.' or ‘->' or between unary operators and operands.

   Pointer modifiers "*" and reference modifiers "&" in declarations are grouped with the type, not the variable. Overloaded operators immediately follow the key word operator, with no intervening white space.

   Example:

       char* p = "hello";
   
       Complex operator+ (const Complex& op1, const Complex& op2);
   

3. Comments

   Comments should be used liberally to explain what code is doing and why, but should not duplicate information readily discernable in the code itself. Comments are meant to be read by others, so liberal use of white space and blank lines will incre

   Use C++-style comments (i.e. // ), except where commenting out part of the middle of a line (such as unused formal parameters). There should be one space between the double slash and the start of the comment text.

   Example:

       Unsigned draw_rect(unsigned wWidth, unsigned wHeight /*, unsigned wDepth */)
   

   1. Block Comments

      Block comments should have blank lines above and below. A block comment is a comment containing two or more lines.

      Examples:

          // This is a C++ block comment.
          // It has two lines in it.
      
          // This is a single-line comment
      

   2. End of Line Comments

   End of line comments are small annotation tacked on the end of a line of code. They are focused on one or a very line of codes where block comments refer to larger sections of code.

   Example:

       IEmployeeCur = iEmployeeCur + 1;       // Keep the index pointer
                                              // synchronized for OLE clients
   

4. Constants

   Do not use #define to declare constant values. Const or enum should be used instead.

   Example:

       const WORD wMode;
   

   Use enumeration for a set of related constants rather than declaring them separately.

   Example:

       // Incorrect
       const unsigned int iCOLOR_RED = 0;
       const unsigned int iCOLOR_GREEN = 1;
       const unsigned int iCOLOR_BLUE = 2;
   
       // Correct
       enum EColor {eRed, eGreen, eBlue};
   

   Do not repeat const declarations in both source and header files. If it is declared in the header file, it is meant for other modules to share. If it is declared in the source file, only that module is meant to use it.

   Use constant variables, instead of literal constants, especially if used in more than one place.

   Example:

       // Incorrect
       int iID = 1000;
   

       // Correct

   In the .CPP file:

       int iID = iStartingID;
   

   In the .h file:

       const int iStartingID =        1000;
   

5. Variables

   Limit the scope of variables as much as possible.

   Each variable is to be declared in a separate declaration statement.

   Examples:

       // Incorrect
       CString sFilename, &rsDirectory;
   
       // Correct
       CString sFilename;
       CString& rsDirectory;
   

   Define variables close to where they will be used.

   Always initialize variables. Declare and initialize variables no earlier than the point at which their initialization values are known.

   Avoid local variable names that are identical to the names of variables with greater scope.

   Beware of the variable's scope. The variable will often remain in existence longer than originally anticipated.

   1. Global variable definitions

   Global variables are strongly discouraged.

   Do not use global variables that only have module (throughout the current source file only) scope.

6. Classes

   Use struct when there are no private or protected member data and no member functions (including constructors and destructors). In other words, use struct for public data structures. Use class in all other cases.

   Member data and functions should be declared in the following order: public members, protected members, and private members. Always use the access keywords public, protected, and private.

   1. Encapsulation

      Member data in a class should be declared private, not protected or public. This is to adhere to the object-oriented design principle of data encapsulation. If other classes need access to member data, provide get and

      Hide member functions that are not required for the external interface using the private or protected keyword.

      Localize and hide design decisions that may change.

   2. Inheritance

      When using inheritance, specify public for each parent class.

      Example:

      class myClass
      {
          // ….
      }
      
      class derivedClass : public myClass
      {
          // ….
      }
      
      

      In Visual C++, classes that have no other parent class should be derived from CObject. This allows these classes to be part of templated collection classes.

      Avoid multiple inheritance.

   3. Member Functions

      Keep function length to less than two pages. One page is better. Long functions are more difficult to understand and maintain.

      Do not use variable length argument lists (similar to printf).

      Large function parameters should be passed by reference, not by value. If the function is not changing the value of a large parameter, declare that parameter const. Small parameters that won't be changed by the function can be passed by value.

      Whenever an address is returned from a member function, it should be returned as a const pointer or a const reference, unless you want the user to be able to change the contents of what the pointer de-references.

      1. Inline Functions

         Inline functions should not be used, unless performance is known to be a problem. The exception to this rule is access functions, which should be inline, but not within the body of the class.

         Constructors and destructors should not be inline.

         Inline functions should be three lines long or less.

         Example:

             // Incorrect
         
             class CPriority
             {
                 public:
                     int        CPriority() // should not use inline here
                     {
                         doSomething();
                     };
                int getx();
                private:
                    int   x;
             };
         
             int CPriority::getx() // inline should be used here
             {
                 return(x);
             }
         
             // correct
         
             class CPriority
             {
                  public:
                     int        CPriority(); // constructor should not use inline
                     int getx();
         
                  private:
                      int   x;
             };
         
             // constructor
             int CPriority::CPriority()
             {
                 doSomeThing();
             }
         

             inline int CPriority::getx () // get function can use inline
             {
                 return(x);
             }
         

      2. const Member Functions

      A member function that does not affect the state of an object (its member data) is to be declared const. Member functions declared as const may not modify member data and are the only functions that may be invoked on const obj

   4. Constructors and Destructors

      Initialize member data in the class constructor. Pointers should be set to 0 in the constructor and deleted in the destructor.

      Constructors should use initialization, not assignment, to set member data, if possible.

      Example:

          // Incorrect
      
          Catom::Catom(int iAtNum, float fAtWt)
          {
              m_iAtomicNumber = iAtNum;
              m_fAtomicWeight = fAtWt;
          }
      
          // Correct
      
          Catom::Catom(int iAtNum, float fAtWt) : m_iAtomicNumber(iAtNum),
           m_fAtomicWeight(fAtWt)
          {
              ;    // Empty
          }
      

      A class that uses the new keyword to allocate objects managed by the class must define a copy constructor. This is to avoid surprises when an object is initialized using an object of the same type. If an object manages the allocation an

      Example:

          //  Incorrect
      
          class String
          {
              public:
                  String( const char* cp = "");    // constructor
                  ~String();                       // destructor
              private:
                   char *sp;
          };
      
          String::String(const char* cp) : sp ( new char[strlen(cp)] )     // constructor
          {
              strcpy(sp, cp);
          }
      
          String::~String()                            // destructor
          {
              delete sp;
          }
      
          void
          main()
          {
              String w1;
              String w2 = w1;
      
              // Warning:  the destructor for w1::sp will be called twice:
              // first when w1 is destroyed;  again, when w2 is destroyed.
          }
      
          //  Correct
      
          class String
          {
              public:
                  String( const char* cp = "" );    // constructor
                  String( const String& sp );       // copy constructor
                  ~String();                        // destructor
                  // …
               private:
                   char *sp;
                   // …
          };
      
          String::String( const String& stringA ) : sp( new char[strlen(stringA.sp)] )
          {
              strcpy ( sp, stringA.sp );
          }
      
          String::~String()                            // destructor
          {
              delete sp;
          }
      
          void
          main()
          {
              String w1;
              String w2 = w1;     // SAFE COPY:   String::String( const String& ) called.
          }
      

      All classes that are used as base classes and have virtual functions, must define a virtual destructor.

      Avoid the use of global objects in constructors and destructors.

   5. Operator Overloading

      Use operator overloading sparingly and in a uniform manner. One disadvantage in overloading operators is that it is easy to misunderstand the meaning of an overloaded operator

   6. Friends

   Use friend functions sparingly. Friends offer an orderly way of getting around data encapsulation for a class. A friend class can be advantageously used to provide functions that require data that is not normally needed by the class

7. Flow Control Structures

   A break statement must always terminate the code following a case label.

   A switch statement must always contain a default branch that handles unexpected cases.

   If testing the value of a single variable, use a switch statement instead of an if statement.

   The flow control statements if, while, for and do should be followed by a block, even if it is empty or contains a single line.

   Example:

       //Incorrect
   
       while ( !bSomething ) ;
       for ( i = 0; i < 10; i++ )
           cout << aSomeArray[I];
   
       //Correct
   
       while ( !bSomething )
       {
           ;    // Empty
       }
   
       for ( i = 0; i < 10; i++ )
       {
           cout << aSomeArray[I];
       }
   

   Do not embed assignment statements into flow control statements.

   Example:

       // Incorrect
   
       if ( bFlag = GetStatusWrite() )
       {
           ...
       }
   
       // Correct
   
       bFlag = GetStatusWrite();
       if ( bFlag )
       {
           ...
       }
   

   Never use goto. Goto breaks the control flow and can lead to code that is difficult to comprehend.

   Avoid the use of continue. Continue can be used to exit from loops. However, code may be more comprehensible by using an else clause instead.

   1. Boolean Tests

      Only use if (something) and if (!something) when something is a BOOL value. If it is a multi-valued variable or a pointer, test for equality with 0.

      Examples:

          if (!strcmp( myString, "value" )) // Bad
          if (strcmp( myString, "value" ) == 0)  // Good
      

   2. Control Statement Overrides

   Minimize the use of return, break, continue and goto statements which override normal control statement structure. However, each of these statements has a place - use them when the code would be significantly more convo

8. Additional Guidelines
   1. Debugging

      Test the input parameters of a member function for valid data using the assert function.

   2. Exceptions

      Catch exceptions thrown by MFC functions. Use a try-catch block around calls to these functions.

      Example:

          CRecordSet clPriceData;
      
          try
          {
              clPriceData.Open();
          }
          catch (CDBException* pxOpen)
          {
              pxOpen.
          }
      

   3. Unions

      Avoid unions, as they defeat strong type-checking and are very difficult to verify in a debugger.

   4. Use C++ memory management

      Do not use realloc. Malloc, calloc, and free should be avoided; the operators new and delete should be used instead.

      Always use delete whenever memory was allocated by the new operator. In order to help eliminate the problem of accessing memory that has been freed, the pointer must be assigned to 0 after the pointer has been deleted. Note: there are in

   5. Input / Output

      Use the C++-style iostream class, not printf, fprintf, or other C-style input/output routines.

   6. MFC

      Use the BOOL and CString classes provided by MFC, not int (for boolean responses) or char* types from C.

      Use MFC classes where appropriate.

   7. Null Pointer

The C++ language definition unequivocally defines a pointer value of 0 (zero), or any expression that evaluates to zero, as a null pointer. Stroustrup writes, "A constant expression that evaluates to zero is converted to a pointer, commonly c

References