Introduction

Standardization is Important

Good Points

• 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 and defend it to the death.
• People new to C++ are spared making the same mistakes over and over again.
• People make fewer mistakes in consistent environments.
• Programmers have a common enemy :-)

Bad Points

• The standard is usually stupid because it was made by someone who doesn't understand C++.
• The standard is usually stupid because it's not what I do.
• Standards reduce creativity.
• Standards are unnecessary as long as people are consistent.
• Standards enforce too much structure.
• People ignore standards anyway.
• Standards can be used as a reason for NIH (not invented here) because the new/borrowed code won't follow the standard.

Discussion

Interpretation

Conventions

The use of the word "should" directs projects in tailoring a project-specific standard, in that the project must include, exclude, or tailor the requirement, as appropriate.

The use of the word "may" is similar to "should", in that it designates optional requirements.

Terminology

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

Standards Enforcement

In any case, once finalized hopefully people will play the adult and understand that this standard is reasonable, and has been found reasonable by many other programmers, and therefore is worthy of being followed even with personal reservations.

Failing willing cooperation it can be made a requirement that this standard must be followed to pass a code inspection.

Failing that the only solution is a massive tickling party on the offending party.

Accepting an Idea

1. It's impossible.
2. Maybe it's possible, but it's weak and uninteresting.
3. It is true and I told you so.
4. I thought of it first.
5. How could it be otherwise.

6 Phases of a Project

1. Enthusiasm
2. Disillusionment
3. Panic
4. A Search for the Guilty
5. The Punishment of the Innocent
6. Praise and Honor for the Non-Participants

Flow Chart for Project Decision Making

                       +---------+
                       |  START  |
                       +---------+
                            |
                            V
            YES       +------------+      NO
      +---------------|  DOES THE  |---------------+
      |               | DAMN THING |               |
      V               |    WORK?   |               V
+------------+        +------------+        +--------------+  NO
| DON'T FUCK |                              | DID YOU FUCK |-----+
| WITH IT    |                              |   WITH IT?   |     |
+------------+                              +--------------+     |
      |                                            |             |
      |                                            | YES         |
      |                                            V             |
      |  +------+     +-------------+       +---------------+    |
      |  | HIDE |  NO | DOES ANYONE |<------| YOU DUMBSHIT! |    |
      |  |  IT  |<----|    KNOW?    |       +---------------+    |
      |  +------+     +-------------+                            |
      |      |               |                                   |
      |      |               V                                   |
      |      |        +-------------+       +-------------+      |
      |      |        |   YOU POOR  |  YES  |  WILL YOU   |      |
      |      |        |   BASTARD   |<------| CATCH HELL? |<-----+
      |      |        +-------------+       +-------------+
      |      |               |                     |
      |      |               |                     | NO
      |      |               V                     V
      |      V        +-------------+       +------------+
      +-------------->|    STOP     |<------| SHITCAN IT |
                      +-------------+       +------------+

Resources- Take a Look!

• Design Stories
• OO Info Sources
• Unified Modeling Language (UML)
• OPEN Method
• OO FAQ - All You Wanted to Know About OO
• C++ FAQ - All You Wanted to Know About C++
• C++ Source Libraries
• C++ Tutorials
• ACE C++ Library
• Collection of Other Standards
• Design by Contract from Eiffle
• C++ isn't Perfect, Here are Some Reasons Why
• ccdoc - is a 'javadoc' like utility that extracts comments and relevant information from your C++/C programs and generates HTML pages from it.
• Const Correctness - A very nice article on const correctness by Chad Loder.
• Introduction to CRC Cards - A very nice introdction to CRC cards.
• Abraxis Code Check - A program for checking code for coding standard violations and other problems.

Names

Make Names Fit

A name is the result of a long deep thought process about the ecology it lives in. Only a programmer who understands the system as a whole can create a name that "fits" with the system. If the name is appropriate everything fits together naturally, relationships are clear, meaning is derivable, and reasoning from common human expectations works as expected.

If you find all your names could be Thing and DoIt then you should probably revisit your design.

Class Names

• Name the 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.
• Compound names of over three words are a clue your design may be confusing various entities in your system. Revisit your design. Try a CRC card session to see if your objects have more responsibilities than they should.
• Avoid the temptation of bringing the name of the class a class derives from into the derived class's name. A class should stand on its own. It doesn't matter what it derives from.
• Suffixes are sometimes helpful. For example, if your system uses agents then naming something DownloadAgent conveys real information.

Method and Function Names

• Usually every method and function performs an action, so the name should make clear what it does: CheckForErrors() instead of ErrorCheck(), DumpDataToFile() instead of DataFile(). This will also make functions and data objects more distinguishable.

  Classes are often nouns. By making function names verbs and following other naming conventions programs can be read more naturally.

• Suffixes are sometimes useful:
  • Max - to mean the maximum value something can have.
  • Cnt - the current count of a running count variable.
  • Key - key value.

  For example: RetryMax to mean the maximum number of retries, RetryCnt to mean the current retry count.

• Prefixes are sometimes useful:
  • Is - to ask a question about something. Whenever someone sees Is they will know it's a question.
  • Get - get a value.
  • Set - set a value.

  For example: IsHitRetryLimit.

Include Units in Names

uint32 mTimeoutMsecs;
uint32 mMyWeightLbs;

No All Upper Case Abbreviations

• When confronted with a situation where you could use an all upper case abbreviation instead use an initial upper case letter followed by all lower case letters. No matter what.

Justification

• People seem to have very different intuitions when making names containing abbreviations. It's best to settle on one strategy so the names are absolutely predictable.

  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

Class Names

• Use upper case letters as word separators, lower case for the rest of a word
• First character in a name is upper case
• No underbars ('_')

Justification

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

Example

   class NameOneTwo

   class Name

Class Library Names

• Now that name spaces are becoming more widely implemented, name spaces should be used to prevent class name conflicts among libraries from different vendors and groups.
• When not using name spaces, it's common to prevent class name clashes by prefixing class names with a unique string. Two characters is sufficient, but a longer length is fine.

Example

   class JjLinkList
   {
   }

Method Names

• Use the same rule as for class names.

Justification

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

Example

   class NameOneTwo
   {
   public:
      int                   DoIt();
      void                  HandleError();
   }

Class Attribute Names

• Attribute names should be prepended with the character 'm'.
• After the 'm' use the same rules as for class names.
• 'm' always precedes other name modifiers like 'p' for pointer.

Justification

• Prepending 'm' prevents any conflict with method names. Often your methods and attribute names will be similar, especially for accessors.

Example

   class NameOneTwo
   {
   public:
      int                   VarAbc();
      int                   ErrorNumber();
   private:
      int                   mVarAbc;
      int                   mErrorNumber;
      String*               mpName;
   }

Method Argument Names

• The first character should be lower case.
• All word beginnings after the first letter should be upper case as with class names.

Justification

• You can always tell which variables are passed in variables.
• You can use names similar to class names without conflicting with class names.

Example

   class NameOneTwo
   {
   public:
      int                   StartYourEngines(
                               Engine& rSomeEngine,
                               Engine& rAnotherEngine);
   }

Variable Names on the Stack

• use all lower case letters
• use '_' as the word separator.

Justification

• With this approach the scope of the variable is clear in the code.
• Now all variables look different and are identifiable in the code.

Example

   int
   NameOneTwo::HandleError(int errorNumber)
   {
      int            error= OsErr();
      Time           time_of_error;
      ErrorProcessor error_processor;
   }

Pointer Variables

• pointers should be prepended by a 'p' in most cases
• place the * close to the pointer type not the variable name

Justification

• The idea is that the difference between a pointer, object, and a reference to an object is important for understanding the code, especially in C++ where -> can be overloaded, and casting and copy semantics are important.
• Pointers really are a change of type so the * belongs near the type. One reservation with this policy relates to declaring multiple variables with the same type on the same line. In C++ the pointer modifier only applies to the closest variable, not all of them, which can be very confusing, especially for newbies. You want to have one declaration per line anyway so you can document each variable.

Example

  String* pName= new String;

  String* pName, name, address; // note, only pName is a pointer.

Reference Variables and Functions Returning References

• References should be prepended with 'r'.

Justification

• The difference between variable types is clarified.
• It establishes the difference between a method returning a modifiable object and the same method name returning a non-modifiable object.

Example

   class Test
   {
   public:
      void               DoSomething(StatusInfo& rStatus);

      StatusInfo&        rStatus();
      const StatusInfo&  Status() const;

   private:
      StatusInfo&        mrStatus;
   }

Global Variables

• Global variables should be prepended with a 'g'.

Justification

• It's important to know the scope of a variable.

Example

    Logger  gLog;
    Logger* gpLog;

Global Constants

• Global constants should be all caps with '_' separators.

Justification

Example

    const int A_GLOBAL_CONSTANT= 5;

Static Variables

• Static variables may be prepended with 's'.

Justification

• It's important to know the scope of a variable.

Example

   class Test
   {
   public:
   private:
      static StatusInfo msStatus;
   }

Type Names

• When possible for types based on native types 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 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;

#define and Macro Names

• Put #defines and macros in all upper using '_' separators.

Justification

Some subtle errors can occur when macro names and enum labels use the same name.

Example

#define MAX(a,b) blah
#define IS_ERR(err) blah

C Function Names

• In a C++ project there should be very few C functions.
• For C functions use the GNU convention of all lower case letters with '_' as the word delimiter.

Justification

• It makes C functions very different from any C++ related names.

Example

   int
   some_bloody_function()
   {
   }

Enum Names

Labels All Upper Case with '_' Word Separators

Example

   enum PinStateType
   {
      PIN_OFF,
      PIN_ON
   };

Enums as Constants without Class Scoping

Example

   enum PinStateType            If PIN was not prepended a conflict
   {                            would occur as OFF and ON are probably
      PIN_OFF,                  already defined.
      PIN_ON
   };

Enums with Class Scoping

Make a Label for an Error State

Example

enum { STATE_ERR,  STATE_OPEN, STATE_RUNNING, STATE_DYING};

Required Methods for a Class

• Default Constructor

  If your class needs a constructor, make sure to provide one. You need one if during the operation of the class it creates something or does something that needs to be undone when the object dies. This includes creating memory, opening file descriptors, opening transactions etc.

  If the default constructor is sufficient add a comment indicating that the compiler-generated version will be used.

  If your default constructor has one or more optional arguments, add a comment indicating that it still functions as the default constructor.

• Virtual Destructor

  If your class is intended to be derived from by other classes then make the destructor virtual.

• Copy Constructor

  If your class is copyable, either define a copy constructor and assignment operator or add a comment indicating that the compiler-generated versions will be used.

  If your class objects should not be copied, make the copy constructor and assignment operator private and don't define bodies for them. If you don't know whether the class objects should be copyable, then assume not unless and until the copy operations are needed.

• Assignment Operator

  If your class is assignable, either define a assignment operator or add a comment indicating that the compiler-generated versions will be used.

  If your objects should not be assigned, make the assignment operator private and don't define bodies for them. If you don't know whether the class objects should be assignable, then assume not.

Justification

• Virtual destructors ensure objects will be completely destructed regardless of inheritance depth. You don't have to use a virtual destructor when:
  • You don't expect a class to have descendants.
  • The overhead of virtualness would be too much.
  • An object must have a certain data layout and size.
• A default constructor allows an object to be used in an array.
• The copy constructor and assignment operator ensure an object is always properly constructed.

The Law of The Big Three

Example

class Planet
{
public:
  // The following is the default constructor if
  // no arguments are supplied:
  //
  Planet(int radius= 5);

  // Use compiler-generated copy constructor, assignment, and destructor.
  // Planet(const Planet&);
  // Planet& operator=(const Planet&);
  // ~Planet();
};

Braces {} Policy

Brace Placement

• Place brace under and inline with keywords:

     if (condition)        while (condition)
     {                     {
        ...                   ...
     }                     }
  

• Traditional Unix policy of placing the initial brace on the same line as the keyword and the trailing brace inline on its own line with the keyword:

     if (condition) {      while (condition) {
        ...                   ...
     }                     }
  

Justification

• Another religious issue of great debate solved by compromise. Either form is acceptable, many people, however, find the first form more pleasant. Why is the topic of many psychological studies.

  There are more reasons than psychological for preferring the first style. If you use an editor (such as vi) that supports brace matching, the first is a much better style. Why? Let's say you have a large block of code and want to know where the block ends. You move to the first brace hit a key and the editor finds the matching brace. Example:

       if (very_long_condition && second_very_long_condition)
       {
          ...
       }
       else if (...)
       {
  	..
       }
  

  To move from block to block you just need to use cursor down and your brace matching key. No need to move to the end of the line to match a brace then jerk back and forth.

When Braces are Needed

Always Uses Braces Form

if (1 == somevalue)
{
   somevalue = 2;
}

Justification

One Line Form

if (1 == somevalue) somevalue = 2;

Justification

Add Comments to Closing Braces

while(1)
{
   if (valid)
   {

   } // if valid
   else
   {
   } // not valid

} // end forever

Consider Screen Size Limits

Indentation/Tabs/Space Policy

• Indent using 3, 4, or 8 spaces for each level.
• Do not use tabs, use spaces. Most editors can substitute spaces for tabs.
• Tabs should be fixed at 8 spaces. Don't set tabs to a different spacing, uses spaces instead.
• Indent as much 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 8 space indentation severely limits the number of indentation levels one can have. The argument that if this is a problem you have too many indentation levels has some force, but real code can often be three or more levels deep. Changing a tab to be less than 8 spaces is a problem because that setting is usually local. When someone prints the source tabs will be 8 characters and the code will look horrible. Same for people using other editors. Which is why we use spaces...
• When people using different tab settings the code is impossible to read or print, which is why spaces are preferable to tabs.
• Nobody can ever agree on the correct number of spaces, just be consistent. In general people have found 3 or 4 spaces per indentation level workable.
• 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()
   {
      if (something bad)
      {
         if (another thing bad)
         {
            while (more input)
            {
            }
         }
      }
   }

Parens () with Key Words and Functions Policy

• Do not put parens next to keywords. Put a space between.
• Do put parens next to function names.
• Do not use parens in return statements when it's not necessary.

Justification

• Keywords are not functions. By putting parens next to keywords keywords and function names are made to look alike.

Example

    if (condition)
    {
    }

    while (condition)
    {
    }

    strcpy(s, s1);

    return 1;

RCS Keywords, Change Log, and History Policy

• Do not use RCS keywords within files.
• Do not keep a change history in files.
• Do not keep author information in files.

Justification

• The reasoning is your source control system already keeps all this information. There is no reason to clutter up source files with duplicate information that:
  • makes the files larger
  • makes doing diffs difficult as non source code lines change
  • makes the entry into the file dozens of lines lower in the file which makes a search or jump necessary for each file
  • is easily available from the source code control system and does not need embedding in the file
• When files must be sent to other organizations the comments may contain internal details that should not be exposed to outsiders.

Class Layout

Class and Method Documentation

Template

/**
 * A one line description of the class.
 *
 * #include "XX.h" <BR>
 * -llib
 *
 * A longer description.
 *
 * @see something
 */

#ifndef XX_h
#define XX_h

// SYSTEM INCLUDES
//

// PROJECT INCLUDES
//

// LOCAL INCLUDES
//

// FORWARD REFERENCES
//


class XX
{
public:
// LIFECYCLE

   /**
    * Default constructor.
	*/
   XX(void);

   /**
    * Copy constructor.
	*
	* @param from The value to copy to this object.
	*/
   XX(const XX& from);

   /**
    * Destructor.
	*/
   ~XX(void);

// OPERATORS

   /**
    * Assignment operator.
	*
	* @param from THe value to assign to this object.
	*
	* @return A reference to this object.
	*/
   XX&                     operator=(XX& from);

// OPERATIONS
// ACCESS
// INQUIRY

protected:
private:
};

// INLINE METHODS
//

// EXTERNAL REFERENCES
//

#endif  // _XX_h_

Required Methods Placeholders

Method Layout

Method Header

  /**
   * Assignment operator.
   *
   * @param val The value to assign to this object.
   *
   * @return A reference to this object.
   */
   XX&                     operator=(XX& val);

Additional Sections

1. PRECONDITION
   Document what must have happened for the object to be in a state where the method can be called.

2. WARNING
   Document anything unusual users should know about this method.

3. LOCK REQUIRED
   Some methods require a semaphore be acquired before using the method. When this is the case use lock required and specify the name of the lock.

4. EXAMPLES
   Include exampes of how to use a method. A picture says a 1000 words, a good example answers a 1000 questions.

  /**
   * Copy one string to another.
   *
   * PRECONDITION

   * REQUIRE(from != 0)
   * REQUIRE(to != 0)
   *
   * WARNING

   * The to buffer must be long enough to hold
   * the entire from buffer.
   *
   * EXAMPLES

   * 
   * strcpy(somebuf, "test")
   * 
   *
   * @param from The string to copy.
   * @param to The buffer to copy the string to.
   *
   * @return void
   */
   void  strcpy(const char* from, char* to);

Common Exception Sections

Formatting Methods with Multiple Arguments

   int                     AnyMethod(
                              int   arg1,
                              int   arg2,
                              int   arg3,
                              int   arg4);

Include Statement Documentation

• ISA
• HASA
• USES

Example

#ifndef XX_h
#define XX_h

// SYSTEM INCLUDES
//
#include                              // standard IO interface
#include                             // HASA string interface

Block Comments

{
   // Block1  (meaningful comment about Block1)
  ... some code

  {
     // Block2  (meaningful comment about Block2)
     ... some code
  }  // End Block2

}  // End Block1

Think About What Work to do in Constructors

   class Device
   {
   public:
      Device()    { /* initialize and other stuff */ }
      int Open()  { return FAIL; }
   };

   Device dev;
   if (FAIL == dev.Open()) exit(1);

The constructor code must still be very careful not to leak resources in the constructor. It's possible to throw an exception and not destruct objects allocated in the constructor.

There is a pattern called Resource Acquisition as Initialization that says all initialization is performed in the constructor and released in the destructor. The idea is that this is a safer approach because it should reduce resource leaks.

Be Careful Throwing Exceptions in Destructors

The logic might look like:

Sql::~Sql()
{
   delete connection;
   delete buffer;
}

Let's say an exception is thrown while deleting the database connection. Will the buffer be deleted? No. Exceptions are basically non-local gotos with stack cleanup. The code for deleting the buffer will never be executed creating a gaping resource leak.

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.

Prototype Source File

#include "XX.h"                                // class implemented


/////////////////////////////// PUBLIC ///////////////////////////////////////

//============================= LIFECYCLE ====================================

XX::XX()
{
}// XX

XX::XX(const XX&)
{
}// XX

XX::~XX()
{
}// ~XX


//============================= OPERATORS ====================================

XX&
XX::operator=(XX&);
{
   return *this;

}// =

//============================= OPERATIONS ===================================
//============================= ACESS      ===================================
//============================= INQUIRY    ===================================
/////////////////////////////// PROTECTED  ///////////////////////////////////

/////////////////////////////// PRIVATE    ///////////////////////////////////

Use of Namespaces

Naming Policy

Don't Globally Define using

Make Functions Reentrant

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

To Use Enums or Not to Use Enums

In general enums are preferred to #define as enums are understood by the debugger.

Be aware enums are not of a guaranteed size. So if you have a type that can take a known range of values and it is transported in a message you can't use an enum as the type. Use the correct integer size and use constants or #define. Casting between integers and enums is very error prone as you could cast a value not in the enum.

A C++ Workaround

Example

class Variables
{
public:
   static const int   A_VARIABLE;
   static const int   B_VARIABLE;
   static const int   C_VARIABLE;
}

Use Header File Guards

When Not Using Namespces

#ifndef filename_h
#define filename_h

#endif

When Using Namespaces

#ifndef namespace_filename_h
#define namespace_filename_h

#endif

1. Replace filename with the name of the file being guarded. This should usually be the name of class contained in the file. Use the exact class name. Some standards say use all upper case. This is a mistake because someone could actually name a class the same as yours but using all upper letters. If the files end up be included together one file will prevent the other from being included and you will be one very confused puppy. It has happened!

2. Most standards put a leading _ and trailing _. This is no longer valid as the C++ standard reserves leading _ to compiler writers.

3. When the include file is not for a class then the file name should be used as the guard name.

4. Compilers differ on how comments are handled on preprocessor directives. Historically many compilers have not accepted comments on preprocessor directives.

5. Historically many compilers require a new line after last endif.

A Line Should Not Exceed 78 Characters

• Lines should not exceed 78 characters.

Justification

• Even though with big monitors we stretch windows wide our printers can only print so wide. And we still need to print code.
• The wider the window the fewer windows we can have on a screen. More windows is better than wider windows.
• We even view and print diff output correctly on all terminals and printers.

If Then Else Formatting

Layout

   if (condition)                 // Comment
   {
   }
   else if (condition)            // Comment
   {
   }
   else                           // Comment
   {
   }

Condition Format

if ( 6 == errorNum ) ...

One reason is that if you leave out one of the = signs, the compiler will find the error for you. A second reason is that it puts the value you are looking for right up front where you can find it instead of buried at the end of your expression. It takes a little time to get used to this format, but then it really gets useful.

switch Formatting

• Falling through a case statement into the next case statement shall be permitted as long as a comment is included.
• The default case should always be present and trigger an error if it should not be reached, yet is reached.
• If you need to create variables put all the code in a block.

Example

   switch (...)
   {
      case 1:
         ...
      // FALL THROUGH

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

      default:
   }

Use of goto,continue,break and ?:

Goto

   for (...)
   {
      while (...)
      {
         ...
         if (disaster)
            goto error;
      }
   }
   ...
error:
   clean up the mess

When a goto is necessary the accompanying label should be alone on a line and to the left of the code that follows. The goto should be commented (possibly in the block header) as to its utility and purpose.

Continue and Break

Continue and break like goto should be used sparingly as they are magic in code. With a simple spell the reader is beamed to god knows where for some usually undocumented reason.

The two main problems with continue are:

• It may bypass the test condition
• It may bypass the increment/decrement expression

Consider the following example where both problems occur:

while (TRUE)
{
   ...
   // A lot of code
   ...
   if (/* some condition */) {
      continue;
   }
   ...
   // A lot of code
   ...
   if ( i++ > STOP_VALUE) break;
}

From the above example, a further rule may be given: Mixing continue with break in the same loop is a sure way to disaster.

?:

• Put the condition in parens so as to set it off from other code
• If possible, the actions for the test should be simple functions.
• Put the action for the then and else statement on a separate line unless it can be clearly put on one line.

Example

   (condition) ? funct1() : func2();

   or

   (condition)
      ? long statement
      : another long statement;

Alignment of Declaration Blocks

• Block of declarations should be aligned.

Justification

• Clarity.
• Similarly blocks of initialization of variables should be tabulated.
• The ‘&’ and ‘*’ tokens should be adjacent to the type, not the name.

Example

   DWORD       mDword
   DWORD*      mpDword
   char*       mpChar
   char        mChar

   mDword   = 0;
   mpDword  = NULL;
   mpChar   = NULL;
   mChar    = 0;

Macros

Don't Turn C++ into Pascal

Replace Macros with Inline Functions

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);
   }

Be Careful of Side Effects

Example

   MAX(f(x),z++);

Always Wrap the Expression in Parenthesis

Example

#define ADD(x,y) x + y

must be written as

#define ADD(x,y) (x + y)

Make Macro Names Unique

1. Prepend macro names with package names.
2. Avoid simple and common names like MAX and MIN.

Initialize all Variables

• You shall always initialize variables. 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 Init Idiom for Initializing Objects .

Init Idiom for Initializing Objects

• Objects with multiple constructors and/or multiple attributes should define a private Init() method to initialize all attributes. If the number of different member variables is small then this idiom may not be a big win and C++'s constructor initialization syntax can/should be used.

Justification

• When using C++'s ability to initialize variables in the constructor it's difficult with multiple constructors and/or multiple attributes to make sure all attributes are initialized. When an attribute is added or changed almost invariably we'll miss changing a constructor.

  It's better to define one method, Init(), that initializes all possible attributes. Init() should be called first from every constructor.

• The Init() idiom cannot be used in two cases where initialization from a constructor is required:
  • constructing a member object
  • initializing a member attribute that is a reference

Example

   class Test
   {
   public:
      Test()
      {
         Init();   // Call to common object initializer
      }

      Test(int val)
      {
         Init();   // Call to common object initializer
         mVal= val;
      }

   private:
      int      mVal;
      String*  mpName;

      void Init()
      {
         mVal  = 0;
         mpName= 0;
      }
   }

Since the number of member variables is small, this might be better
written as:

   class Test
   {
   public:
     Test(int val = 0, String* name = 0)
       : mVal(val), mpName(name) {}
   private:
     int         mVal;
     String*     mpName;
   };

One Statement Per Line

The reasons are:

1. The code is easier to read. Use some white space too. Nothing better than to read code that is one line after another with no white space or comments.

One Variable Per Line

Not:
char **a, *x;

Do:
char** a= 0;  // add doc
char*  x= 0;  // add doc

1. Documentation can be added for the variable on the line.
2. It's clear that the variables are initialized.
3. Declarations are clear which reduces the probablity of declaring a pointer when you meant to declare just a char.

Short Methods

• Methods should limit themselves to a single page of code.

Justification

• The idea is that the each method represents a technique for achieving a single objective.
• Most arguments of inefficiency turn out to be false in the long run.
• True function calls are slower than not, but there needs to a thought out decision (see premature optimization).

Document Null Statements

   while (*dest++ = *src++)
      ;         // VOID

Do Not Default If Test to Non-Zero

   if (FAIL != f())

   if (f())

   #define STREQ(a, b) (strcmp((a), (b)) == 0)

Or better yet use an inline method:

   inline bool
   StringEqual(char* a, char* b)
   {
      (strcmp(a, b) == 0) ? return true : return false;
	  Or more compactly:
      return strcmp(a, b) == 0;
   }

Note, this is just an example, you should really use the standard library string type for doing the comparison.

The non-zero test is often defaulted for predicates and other functions or expressions which meet the following restrictions:

• Returns 0 for false, nothing else.
• Is named so that the meaning of (say) a true return is absolutely obvious. Call a predicate IsValid(), not CheckValid().

The Bull of Boolean Types

The form of boolean most accurately matching the new standard is:

   typedef int     bool;
   #define TRUE    1
   #define FALSE   0

or

   const int TRUE  = 1;
   const int FALSE = 0;

Even with these declarations, do not check a boolean value for equality with 1 (TRUE, YES, etc.); instead test for inequality with 0 (FALSE, NO, etc.). Most functions are guaranteed to return 0 if false, but only non-zero if true. Thus,

   if (TRUE == func()) { ...

   if (FALSE != func()) { ...

Usually Avoid Embedded Assignments

   while (EOF != (c = getchar()))
   {
      process the character
   }

The ++ and -- operators count as assignment statements. So, for many purposes, do functions with side effects. Using embedded assignment statements to improve run-time performance is also possible. However, one should consider the tradeoff between increased speed and decreased maintainability that results when embedded assignments are used in artificial places. For example,

   a = b + c;
   d = a + r;

   d = (a = b + c) + r;

Reusing Your Hard Work and the Hard Work of Others

Developing a common framework takes a lot of up front design effort. When this effort is not made, for whatever reasons, there are several techniques one can use to encourage reuse:

Ask! Email a Broadcast Request to the Group

If you need a piece of code email to the group asking if someone has already done it. The results can be surprising.

In most large groups individuals have no idea what other people are doing. You may even find someone is looking for something to do and will volunteer to do the code for you. There's always a gold mine out there if people work together.

Tell! When You do Something Tell Everyone

Don't be Afraid of Small Libraries

One reason for this is because people don't like making small libraries. There's something about small libraries that doesn't feel right. Get over it. The computer doesn't care how many libraries you have.

If you have code that can be reused and can't be placed in an existing library then make a new library. Libraries don't stay small for long if people are really thinking about reuse.

If you are afraid of having to update makefiles when libraries are recomposed or added then don't include libraries in your makefiles, include the idea of services. Base level makefiles define services that are each composed of a set of libraries. Higher level makefiles specify the services they want. When the libraries for a service change only the lower level makefiles will have to change.

Keep a Repository

In an ideal world a programmer could go to a web page, browse or search a list of packaged libraries, taking what they need. If you can set up such a system where programmers voluntarily maintain such a system, great. If you have a librarian in charge of detecting reusability, even better.

Another approach is to automatically generate a repository from the source code. This is done by using common class, method, library, and subsystem headers that can double as man pages and repository entries.

Comments on Comments

Comments Should Tell a Story

Document Decisions

Use Headers

These headers are structured in such a way as they can be parsed and extracted. They are not useless like normal headers. So take time to fill them out. If you do it right once no more documentation may be necessary. See Class Layout for more information.

Comment Layout

Make Gotchas Explicit

Gotcha Keywords

• :TODO: topic
  Means there's more to do here, don't forget.

• :BUG: [bugid] topic
  means there's a Known bug here, explain it and optionally give a bug ID.

• :KLUDGE:
  When you've done something ugly say so and explain how you would do it differently next time if you had more time.

• :TRICKY:
  Tells somebody that the following code is very tricky so don't go changing it without thinking.

• :WARNING:
  Beware of something.

• :COMPILER:
  Sometimes you need to work around a compiler problem. Document it. The problem may go away eventually.

• :ATTRIBUTE: value
  The general form of an attribute embedded in a comment. You can make up your own attributes and they'll be extracted.

Gotcha Formatting

• Make the gotcha keyword the first symbol in the comment.
• Comments may consist of multiple lines, but the first line should be a self-containing, meaningful summary.
• The writer's name and the date of the remark should be part of the comment. This information is in the source repository, but it can take a quite a while to find out when and by whom it was added. Often gotchas stick around longer than they should. Embedding date information allows other programmer to make this decision. Embedding who information lets us know who to ask.

Example

   // :TODO: tmh 960810: possible performance problem
   // We should really use a hash table here but for now we'll
   // use a linear search.

   // :KLUDGE: tmh 960810: possible unsafe type cast
   // We need a cast here to recover the derived type. It should
   // probably use a virtual method or template.

See Also

Interface and Implementation Documentation

• Class Users
• Class Implementors

Class Users

Class Implementors

Directory Documentation

• the purpose of the directory and what it contains
• a one line comment on each file. A comment can usually be extracted from the NAME attribute of the file header.
• cover build and install directions
• direct people to related resources:
  • directories of source
  • online documentation
  • paper documentation
  • design documentation
• anything else that might help someone

Follow the Law of Demeter

Justification

Caveat

Example

   class SunWorkstation
   {
   public:
      void          UpVolume(int amount) { mSound.Up(amount); }

      SoundCard     mSound;

   private:
      GraphicsCard  mGraphics;
   }

   SunWorksation sun;

   Do   : sun.UpVolume(1);
   Don't: sun.mSound.Up(1);

Minimize Dependencies with Abstract Base Classes

An ABC is an abstraction of a common form such that it can be used to build more specific forms. An ABC is a common interface that is reusable across a broad range of similar classes. By specifying a common interface as long as a class conforming to that interface is used it doesn't really matter what is the type of the derived type. This breaks code dependencies. New classes, conforming to the interface, can be substituted in at will without breaking code. In C++ interfaces are specified by using base classes with virtual methods.

The above is a bit rambling because it's a hard idea to convey. So let's use an example: We are doing a GUI where things jump around on the screen. One approach is to do something like:

   class Frog
   {
   public:
      void Jump();
   }
   class Bean
   {
   public:
      void Jump();
   }

Unfortunately the owner of Bean didn't like the word Jump so they changed the method name to Leap. This broke the code in the GUI and one whole week was lost.

Then someone wanted to see a horse jump so a Horse class was added:

   class Horse
   {
   public:
      void Jump();
   }

Then someone updated Horse so that its Jump behavior was slightly different. Unfortunately this caused a total recompile of the GUI code and they were pissed.

Someone got the bright idea of trying to remove all the above dependencies using abstract base classes. They made one base class that specified an interface for jumping things:

   class Jumpable
   {
   public:
      virtual void Jump() = 0;
   }

Not all methods in an ABC must be pure virtual, some may have an implementation. This is especially true when creating a base class encapsulating a process common to a lot of objects. For example, devices that must be opened, diagnostics run, booted, executed, and then closed on a certain event may create an ABC called Device that has a method called LifeCycle which calls all other methods in turn thus running through all phases of a device's life. Each device phase would have a pure virtual method in the base class requiring implementation by more specific devices. This way the process of using a device is made common but the specifics of a device are hidden behind a common interface.

Back to Jumpable. All the classes were changed to derive from Jumpable:

   class Frog : public Jumpable
   {
   public:
      virtual void Jump() { ... }
   }

   etc ...

Another benefit is that we can pass Jumpable objects to the GUI, not specific objects like Horse or Frog:

   class Gui
   {
   public:
      void MakeJump(Jumpable*);
   }

   Gui gui;
   Frog* pFrog= new Frog;

   gui.MakeJump(pFrog);

We also removed the recompile dependency. Because Gui doesn't contain any Frog objects it will not be recompiled when Frog changes.

Downside

Overhead for Virtual Methods

Make Everything an ABC!

Use a Design Notation and Process

Any project brings together people of widely varying skills, knowledge, and experience. Even if everyone on a project is a genius you will still fail because people will endlessly talk past each other because there is no common language and processes binding the project together. All you'll get is massive fights, burnout, and little progress. If you send your group to training they may not come back seasoned experts but at least your group will all be on the same page; a team.

There are many popular methodologies out there. The point is to do some research, pick a method, train your people on it, and use it. Take a look at the top of this page for links to various methodologies.

You may find the CRC (class responsibility cards) approach to teasing out a design useful. Many others have. It is an informal approach encouraging team cooperation and focusing on objects doing things rather than objects having attributes. There's even a whole book on it: Using CRC Cards by Nancy M. Wilkinson.

Using Use Cases

An individual use case may have a name (although it is typically not a simple name). Its meaning is often written as an informal text description of the external actors and the sequences of events between objects that make up the transaction. Use cases can include other use cases as part of their behaviour.

Requirements Capture

Have as many use cases as needed to describe what a system needs to accomplish.

The Process

• Start by understanding the system you are trying to build.
• Create a set of use cases describing how the system is to be used by all its different audiences.
• Create a class and object model for the system.
• Run through all the use cases to make sure your model can handle all the cases. Update your model and create new use cases as necessary.

Unified Modeling Language

OPEN Method

My guess is UML will win out for marketing reasons. But it is good to have some competition going.

Liskov's Substitution Principle (LSP)

   All classes derived from a base class should be interchangeable
   when used as a base class.

For example, if the Jump method of a Frog object implementing the Jumpable interface actually makes a call and orders pizza we can say its implementation is not in the spirit of Jump and probably all other objects implementing Jump. Before calling a Jump method a programmer would now have to check for the Frog type so it wouldn't screw up the system. We don't want this in programs. We want to use base classes and feel comfortable we will get consistent behaviour.

LSP is a very restrictive idea. It constrains implementors quite a bit. In general people support LSP and have LSP as a goal.

Open/Closed Principle

• open means a class has the ability to be extended.
• closed means a class is closed for modifications other than extension. The idea is 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.

In practice the Open/Closed principle simply means making good use of our old friends abstraction and polymorphism. Abstraction to factor out common processes and ideas. Inheritance to create an interface that must be adhered to by derived classes. In C++ we are talking about using abstract base classes . A lot.

Design by Contract

The contract is enforced in languages like Eiffel by pre and post condition statements that are actually part of the language. In other languages a bit of faith is needed.

Design by contract when coupled with language based verification mechanisms is a very powerful idea. It makes programming more like assembling spec'd parts.

Don't Over Use Operators

Justification

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

Naming Class Files

Class Definition in One File

   ClassName.h

Implementation in One File

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

But When it Gets Really Big...

   ClassName_section.C

Miscellaneous

• Don't use floating-point variables where discrete values are needed. Using a float for a loop counter is a great way to shoot yourself in the foot. Always test floating-point numbers as <= or >=, never use an exact comparison (== or !=).

• Compilers have bugs. Common trouble spots include structure assignment and bit fields. You cannot generally predict which bugs a compiler has. You could write a program that avoids all constructs that are known broken on all compilers. You won't be able to write anything useful, you might still encounter bugs, and the compiler might get fixed in the meanwhile. Thus, you should write ``around'' compiler bugs only when you are forced to use a particular buggy compiler.

• Do not rely on automatic beautifiers. The main person who benefits from good program style is the programmer him/herself, and especially in the early design of handwritten algorithms or pseudo-code. Automatic beautifiers can only be applied to complete, syntactically correct programs and hence are not available when the need for attention to white space and indentation is greatest. Programmers can do a better job of making clear the complete visual layout of a function or file, with the normal attention to detail of a careful programmer (in other words, some of the visual layout is dictated by intent rather than syntax and beautifiers cannot read minds). Sloppy programmers should learn to be careful programmers instead of relying on a beautifier to make their code readable. Finally, since beautifiers are non-trivial programs that must parse the source, a sophisticated beautifier is not worth the benefits gained by such a program. Beautifiers are best for gross formatting of machine-generated code.

• Accidental omission of the second ``='' of the logical compare is a problem. The following is confusing and prone to error.

          if (abool= bbool) { ... }
       

  Does the programmer really mean assignment here? Often yes, but usually no. The solution is to just not do it, an inverse Nike philosophy. Instead use explicit tests and avoid assignment with an implicit test. The recommended form is to do the assignment before doing the test:

  
         abool= bbool;
         if (abool) { ... }
      

• Modern compilers will put variables in registers automatically. Use the register sparingly to indicate the variables that you think are most critical. In extreme cases, mark the 2-4 most critical values as register and mark the rest as REGISTER. The latter can be #defined to register on those machines with many registers.

Be Const Correct

For more information see Const Correctness in the C++ FAQ.

Use Streams

Type Safety

Standard Interface

Interchangeablity of Streams

Streams Got Better

Check Thread Safety

But Not Perfect

Use #if Not #ifdef

#ifdef DEBUG
        temporary_debugger_break();
#endif

cc -c lurker.cpp -DDEBUG=0

#if DEBUG
        temporary_debugger_break();
#endif

#if !defined(USER_NAME)
 #define USER_NAME "john smith"
#endif

Commenting Out Large Code Blocks

Using #if 0

   void
   example()
   {
      great looking code

      #if 0
      lots of code
      #endif

      more code
    }

You can't use /**/ style comments because comments can't contain comments and surely a large block of your code will contain a comment, won't it?

Don't use #ifdef as someone can unknowingly trigger ifdefs from the compiler command line.

Use Descriptive Macro Names Instead of 0

Use Descriptive Macro Names Instead of #if 0

#if NOT_YET_IMPLEMENTED

#if OBSOLETE

#if TEMP_DISABLED

Add a Comment to Document Why

Register/Dispatch Idiom

RDI separates producers and consumers on a distributed scale. Event producers and consumers don't have to know about each other at all. Consumers can drop out of the event stream by deregistering for events. New consumers can register for events at anytime. Event producers can drop out with no ill effect to event consumers, the consumer just won't get any more events. It is a good idea for producers to have an "I'm going down event" so consumers can react intelligently.

Logically the dispatch system is a central entity. The implementation however can be quite different. For a highly distributed system a truly centralized event dispatcher would be a performance bottleneck and a single point of failure. Think of event dispatchers as being a lot of different processes cast about on various machines for redundancy purposes. Event processors communicate amongst each other to distribute knowledge about event consumers and producers. Much like a routing protocol distributes routing information to its peers.

RDI works equally well in the small, in processes and single workstations. Parts of the system can register as event consumers and event producers making for a very flexible system. Complex decisions in a system are expressed as event registrations and deregistrations. No further level of cooperation required.

More expressive event filters can also be used. The above proposal filters events on some unique ID. Often you want events filtered on more complex criteria, much like a database query. For this to work the system has to understand all data formats. This is easy if you use a common format like attribute value pairs. Otherwise each filter needs code understanding packet formats. Compiling in filter code to each dispatcher is one approach. Creating a downloadable generic stack based filter language has been used with success on other projects, being both simple and efficient.

Different Accessor Styles

Why Accessors?

To see why ask yourself:

• 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?

Accessors Considered Somewhat Harmful

Implementing Accessors

Get/Set

   class X
   {
   public:
      int    GetAge() const     { return mAge; }
      void   SetAge(int age)    { mAge= age; }
   private:
      int mAge;
   }

• It's ugly. Get and Set are strewn throughout the code cluttering it up.
• It doesn't treat attributes as objects in their own right. An object will have an assignment operator. Why shouldn't age be an object and have its own assignment operator?

One Method Name

   class X
   {
   public:
      int    Age() const     { return mAge; }
      void   Age(int age)    { mAge= age; }
   private:
      int mAge;
   }

Attributes as Objects

   class X
   {
   public:
      int              Age() const     { return mAge; }
      int&             rAge()          { return mAge; }

      const String&    Name() const    { return mName; }
      String&          rName()         { return mName; }
   private:
      int              mAge;
      String           mName;
   }

When using an int type, which is not a real object, the int is set directly because rAge() returns a reference. The object can do no checking of the value or do any representation reformatting. For many simple attributes, however, these are not horrible restrictions. A way around this problem is to use a class wrapper around base types like int.

When an object is returned as reference its = operator is invoked to complete the assignment. For example:

   X x;
   x.rName()= "test";

When possible use this approach to attribute access.

Layering

A layering violation simply means we have dependency between layers that is not controlled by a well defined interface. When one of the layers changes code could break. We don't want code to break so we want layers to work only with other adjacent layers.

Sometimes we need to jump layers for performance reasons. This is fine, but we should know we are doing it and document appropriately.

Delegation

Delegation is an alternative to using inheritance for implementation purposes. One can use inheritance to define an interface and delegation to implement the interface.

Some people feel delegation is a more robust form of OO than using implementation inheritance. Delegation encourages the formation of abstract class interfaces and HASA relationships. Both of which encourage reuse and dependency breaking.

Example

   class TestTaker
   {
   public:
      void WriteDownAnswer()   { mPaidTestTaker.WriteDownAnswer(); }
   private:
      PaidTestTaker  mPaidTestTaker;
   }

Code Reviews

My god he's questioning code reviews, he's not an engineer!

Not really, it's the form of code reviews and how they fit into normally late chaotic projects is what is being questioned.

First, code reviews are way too late to do much of anything useful. What needs reviewing are requirements and design. This is where you will get more bang for the buck.

Get all relevant people in a room. Lock them in. Go over the class design and requirements until the former is good and the latter is being met. Having all the relevant people in the room makes this process a deep fruitful one as questions can be immediately answered and issues immediately explored. Usually only a couple of such meetings are necessary.

If the above process is done well coding will take care of itself. If you find problems in the code review the best you can usually do is a rewrite after someone has sunk a ton of time and effort into making the code "work."

You will still want to do a code review, just do it offline. Have a couple people you trust read the code in question and simply make comments to the programmer. Then the programmer and reviewers can discuss issues and work them out. Email and quick pointed discussions work well. This approach meets the goals and doesn't take the time of 6 people to do it.

Honor Responsibilities

Face it, if you don't own a piece of code you can't possibly be in a position to change it. There's too much context. Assumptions seemingly reasonable to you may be totally wrong. If you need a change simply ask the responsible person to change it. Or ask them if it is OK to make such-n-such a change. If they say OK then go ahead, otherwise holster your editor.

Every rule has exceptions. If it's 3 in the morning and you need to make a change to make a deliverable then you have to do it. If someone is on vacation and no one has been assigned their module then you have to do it. If you make changes in other people's code try and use the same style they have adopted.

Programmers need to mark with comments code that is particularly sensitive to change. If code in one area requires changes to code in an another area then say so. If changing data formats will cause conflicts with persistent stores or remote message sending then say so. If you are trying to minimize memory usage or achieve some other end then say so. Not everyone is as brilliant as you.

The worst sin is to flit through the system changing bits of code to match your coding style. If someone isn't coding to the standards then ask them or ask your manager to ask them to code to the standards. Use common courtesy.

Code with common responsibility should be treated with care. Resist making radical changes as the conflicts will be hard to resolve. Put comments in the file on how the file should be extended so everyone will follow the same rules. Try and use a common structure in all common files so people don't have to guess on where to find things and how to make changes. Checkin changes as soon as possible so conflicts don't build up.

As an aside, module responsibilities must also be assigned for bug tracking purposes.

Process Automation

Process automation also frees up developers to do real work because they don't have to babysit builds and other project time sinks.

Automated Builds and Error Assignment

This is the best way to maintain a clean build. Make sure the list of all errors for a build is available for everyone to see so everyone can see everyone elses errors. The goal is replace a blaim culture with a culture that tries to get things right and fixes them when they are wrong. Immediate feedback makes this possible.

Automated Code Checking

This feature like the automated error assignment makes problems immediately visible and immediately correctable, all without a lot of blame and shame.

Documentation Extraction

Connect Source Code Control System and Bug Tracking System

1. When a check-in of source code fixes a bug then have the check-in automatically tell the bug tracking system that the bug was fixed.
2. When a bug fix is built in a build change the state of the bug to BUILT.
3. Have a submit tool where people ask judges of they can submit a bug fix on the branch.

Tools Agreement

A split might also be done by who is performing the build. For example, an IDE should be able to used in local builds, but the make program would be used for nightly and release builds.

Certain things are easy/trivial/useful with one tool, but hard/complicated/stupid with another tool. Unstated tool assumptions can be the source of a lot of confusion. "Get a better editor" is not always a workable response, though sometimes that's all there is to it!

Non-Blocking Scheduling

The most effective scheduling rule i've used is to schedule so as to unblock others. The idea is to complete the portions of a feature that will unblock those dependent on you. This way development moves along smoothly because more lines of development can be active at a time. For example, instead of implementing the entire database, implement the simple interface and stub it out. People can work for a very long time this way using that portion of the feature that caused others not to block. Plus it's a form of rapid prototyping because you get immediate feedback on these parts. Don't worry about the quality of implementation because it doesn't matter yet.

Using Personas

simply pretend users of the system you're building. You describe
them, in a surprising amount of detail, and then design your
system for them.

I have a standard set of personas that i consider when creating a design/architecture that don't seem to be common. When you write code their are a lot of personas looking over your shoulder:

1. other programmers using the code
2. maintenance
3. extension
4. documentation group
5. training group
6. code review
7. test and validation
8. manufacturing
9. field support
10. first and second line technical support
11. live debugging
12. post crash debugging
13. build system (documentation generation and automatic testing)
14. unit testing
15. system testing
16. source code control
17. code readers
18. legal

You are much more careful and more thorough when you really thing about all the personas, all the different people and all their different roles and purposes.

Source File Extension Discussion

No Data Definitions in Header Files

/*
 * aheader.h
 */
int x = 0;

1. It's bad magic to have space consuming code silently inserted through the innocent use of header files.
2. It's not common practice to define variables in the header file so it will not occur to devellopers to look for this when there are problems.
3. Consider defining the variable once in a .cpp file and use an extern statement to reference it.
4. Consider using a singleton for access to the data.

Mixing C and C++

Calling C Functions from C++

extern "C" int strncpy(...);
extern "C" int my_great_function();
extern "C"
{
   int strncpy(...);
   int my_great_function();
};

Creating a C Function in C++

extern "C" void
a_c_function_in_cplusplus(int a)
{
}

__cplusplus Preprocessor Directive

#ifdef __cplusplus

extern "C" some_function();

#else

extern some_function();

#endif

No Magic Numbers

if      (22 == foo) { start_thermo_nuclear_war(); }
else if (19 == foo) { refund_lotso_money(); }
else if (16 == foo) { infinite_loop(); }
else                { cry_cause_im_lost(); }

#define   PRESIDENT_WENT_CRAZY  (22)
const int WE_GOOFED= 19;
enum
{
   THEY_DIDNT_PAY= 16
};

if      (PRESIDENT_WENT_CRAZY == foo) { start_thermo_nuclear_war(); }
else if (WE_GOOFED            == foo) { refund_lotso_money(); }
else if (THEY_DIDNT_PAY       == foo) { infinite_loop(); }
else                                  { happy_days_i_know_why_im_here(); }