꿈을 꾸다...

Contents

1. Introduction
   • Standardization is Important
   • Interpretation
   • Standards Enforcement
   • Accepting an Idea
   • 6 Phases of a Project (joke)
   • Flow Chart of Project Decision Making (joke)
   • On Leadership
2. Resources- Take a Look!
3. Names
   • Make Names Fit
   • Include Units in Names
   • No All Upper Case Abbreviations
   • Class Names
   • Class Library Names
   • Method Names
   • Class Attribute Names
   • Method Argument Names
   • Variable Names on the Stack
   • Pointer Variables
   • Reference Variables and Functions Returning References
   • Global Variables
   • Global Constants
   • Static Variables
   • Type Names
   • Enum Names
   • #define and Macro Names
   • C Function Names
   • C++ File Extensions
4. Documentation
   • Comments on Comments
   • Comments Should Tell a Story
   • Document Decisions
   • Use Headers
   • Make Gotchas Explicit
   • Interface and Implementation Documentation
   • Directory Documentation
   • Include Statement Documentation
   • Block Comments
5. Complexity Management
   • Layering
   • Minimize Dependencies with Abstract Base Classes
   • Liskov's Substitution Prinicple
   • Open/Closed Principle
   • Register/Dispatch Idiom
   • Delegation
   • Follow the Law of Demeter
   • Design by Contract
6. Classes
   • Naming Class Files
   • Class Layout
   • Order of public/protected/private?
   • What should go in public/protected/private?
   • Prototype Source File
   • Use of Namespaces
   • Use Header File Guards
   • Required Methods for a Class
   • Method Layout
   • Formating Methods with Multiple Arguments
   • Different Accessor Styles
   • Init Idiom for Initializing Objects
   • Initialize all Variables
   • Minimize Inlines
   • Think About What Work to do in Constructors
   • Be Careful Throwing Exceptions in Destructors
   • Be Const Correct
   • Don't Over Use Operators
   • Thin vs. Fat Class Interfaces
   • Short Methods
7. Process
   • Use a Design Notation and Process
   • Using Use Cases
   • Unified Modeling Language
   • OPEN Method
   • Code Reviews
   • Create a Source Code Control System Early and Not Often
   • Create a Bug Tracking System Early and Not Often
   • RCS Keyword, Change Log, and History Policy
   • Honor Responsibilities
   • Process Automation
   • Tools Agreement
   • Non-Blocking Scheduling
   • Using Personas
   • Using CRC Cards by Nancy M. Wilkinson
8. Formatting
   • Brace {} Policy
   • Indentation/Tabs/Space Policy
   • Parens () with Key Words and Functions Policy
   • A Line Should Not Exceed 78 Characters
   • If Then Else Formatting
   • switch Formatting
   • Use of goto,continue,break and ?:
   • One Statement Per Line
   • Alignment of Declaration Blocks
9. Popular Myths
   • Promise of OO
   • You can't use OO and C++ on Embedded Systems
10. Miscellaneous
    • No Magic Numbers
    • Error Return Check Policy
    • To Use Enums or Not to Use Enums
    • Macros
    • Do Not Default If Test to Non-Zero
    • The Bull of Boolean Types
    • Usually Avoid Embedded Assignments
    • Reusing Your Hard Work and the Hard Work of Others
    • Use Streams
    • Commenting Out Large Code Blocks
    • Use #if Not #ifdef
    • Mixing C and C++
    • Alignment of Class Members
    • Miscellaneous
    • No Data Definitions in Header Files
    • Make Functions Reentrant
11. Portability
    • Use Typedefs for Types
    • Alignment of Class Members
    • Minimize Inlines
    • Compiler Dependent Exceptions
    • Compiler Dependent RTTI

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 LITE
• 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:
   }