Contents

1. Introduction
   • Standardization is Important
   • 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!
   • General
   • Book Recommendations
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 Should Tell a Story
   • Document Decisions
   • Use Extractable Headers
   • Comment All Questions a Programmer May Have When Looking at Your Code
   • Make Your Code Discoverable by Browsing
   • Write Comments as You Code
   • 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
   • What should go in public/protected/private?
   • Prototype Source File
   • 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
   • Don't Over Use Operators
   • Thin vs. Thick Class Interfaces
   • Short Methods
   • In a Source file Indicate if a Method is Static or Virtual
7. Process
   • Use a Design Notation and Process
   • Using Use Cases
   • Using Stories
   • Unified Modeling Language
   • Code Reviews
   • Create a Source Code Control System Early and Not Often
   • Create a Bug Tracking System Early and Not Often
   • Create a Wiki System Early and Not Often
   • RCS Keyword, Change Log, and History Policy
   • Honor Responsibilities
   • Process Automation
   • Tools Agreement
   • Non-Blocking Scheduling
   • Using Personas
   • Use a Continuous Build System
   • Code in the Dominant Style
   • Run Unit Tests Before Every Check-in
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
   • Document Null Statements
   • Include static and virtual Key Words in Source File
9. Exceptions
   • Create One Exception for Each Library
   • Selecting Between Exceptions And Asserts
   • Be Careful Throwing Exceptions in Destructors
   • Working With Libaries Using All Sorts of Different Policies
10. Templates
11. Namespaces
    • Create Unique Name Space Names
    • Don't Globally Define using
    • Create Shortcut Names
12. Miscellaneous
    • Be Const Correct
    • Use Streams
    • 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
    • Commenting Out Large Code Blocks
    • Use #if Not #ifdef
    • Creating a C Function in C++
    • Mixing C and C++
    • No Data Definitions in Header Files
    • Make Functions Reentrant
    • Use the Resource Acquisition is Initialization (RAII) Idiom
    • Remove Trailing Whitespace
13. Portability
    • Use Typedefs for Types
    • Alignment of Class Members
    • Compiler Dependent Exceptions
    • Compiler Dependent RTTI
14. Popular Myths
    • Promise of OO
    • You can't use OO and C++ on Embedded Systems

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

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!

General

• Code Reviews. If you are interested in coding standards you may also be interested in Code Review Standards I have created at http://www.possibility.com/epowiki/Wiki.jsp?page=CodeReviews.
• Design Stories
• OO Info Sources
• Designing Qt-Style C++ APIs - A good paper on API I design for C++. I don't agree with everything, but it is good.
• Unified Modeling Language (UML)
• 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
• Doxygen - 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.
• Abraxis Code Check - A program for checking code for coding standard violations and other problems.

Book Recommendations

1. Koenig/Moo's "Accelerated C++"
2. Lippman/Moo's "C++ Primer" 4th Edition
3. Bruce Eckel's "Thinking In C++"
4. Scott Meyers "Effective C++"
5. Dewhurst's "C++ Gotchas"
6. Meyers' "Effective STL"
7. Josuttis' "The C++ Standard Library"
8. Vandevoorde/Josuttis' "C++ Templates"
9. Langer/Kreft's "Standard C++ IOStreams and Locales"
10. Sutter's "Exceptional C++"
11. Sutter's "More Exceptional C++ and Exceptional C++ Style"
12. Martin's "Agile Software Development: Principles, Patterns, and Practices"

Names

uint32 mTimeoutMsecs;
uint32 mMyWeightLbs;

   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 JjLinkList
   {
   }

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

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

How do you handle statics? There's never a reason to have a static local to a function so there's no reason to invent a syntax for it. But like for most absolute rules, there is an exception, that is when making singletons. Use a "s_" prefix in this case. Take a look at Singleton Pattern for more details.

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.

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

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

   private:
      StatusInfo&        mrStatus;
   }

    Logger  gLog;
    Logger* gpLog;

    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;

   enum PinStateType
   {
      PIN_OFF,
      PIN_ON
   };

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

enum { STATE_ERR,  STATE_OPEN, STATE_RUNNING, STATE_DYING};

#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()
   {
   }

Source File Extension Discussion

Document Decisions

Use Extractable 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.

As part of your nighlty build system have a step the generates the documentation from the source. Then index the source using a tool like Lucene. Have a front end to the search so developers can do full text searches on nightly builds and for release builds. This is a wonderfully useful feature.

The next step in automation is to front the repository with a web server documentation can directly refer to a source file with a URL.

Comment All Questions a Programmer May Have When Looking at Your Code

If you think your code is so clear and wonderful that nobody will have any questions then you are lying to yourself. I have never seen a large system with this wonderful self-documenting code feature. I've seen very few small libraries are even a single class that are so wonderfully self-documented.

You have a lot of tools at your disposal to answer questions:

1. A brain to think up the questions you should be answering. Why? Who? When? How? What?
2. Variable names.
3. Class names.
4. Class decomposition.
5. Method decomposition.
6. File names.
7. Documentation at all levels: package, class, method, attribute, inline.

I don't really consider unit tests a question answering device because if you can't understand the code by reading it, reading something else about the code you don't understand won't help you understand it better.

Make Your Code Discoverable by Browsing

Have a logicanl directory structure. Have directories called doc, lib, src, bin, test, pkg, install, etc and whatever, so I at least have some idea where stuff is. People use the weirdest names and lump everything together so that it it can be detangles. Clear thought is evidenced from the beginning by a directory stucture.

Don't put more than one class in a file. Otherwise, how will I know its there when I browse your code? Should I really need to use search to find every last thing? Can't I just poke around the code and find it? I can if you organize your code.

Name your files after your classes. I didn't believe this one until I saw it. Why you name a file different than the class? How I am possibly supposed to know what's in the file otherwise?

Write Comments as You Code

So when you do something document it right then and there. When you create a class- document it. When you create a method- document it. And so on. That way when you finish coding you will also be finished documenting.

I advocate simultaneously writing code, writing tests, and writing documentaiton. Which comes first depends on you and the problem. I don't think there is any rule that says which should come first. On the path to getting stuff done I'll take the entrance that seems easiest to me at the time. Once on the path it's easy to follow the entire trail.

Won't this break the flow? No, I think it improves flow because it keeps you mindful of what you are doing, why you are doing, and how it fits in the big picture. My take on TDD (test driven development) is that it's not the tests that are really important, it's that the tests keep you mindful while programming. A test means you are keeping everything in you mind at once you need to remember to successfully code something up. As you can't keep large chunks in your mind then smaller chunks are better. Writing a test forces you to remember what your code is supposed to accomplish. It's forcing you to also think about the use case/story/intent behind why you are writing the code.

The result is a pointed mind that has focussed all its powers on doing one thing. When you can bring that focus to you programming you can be successful. The tests are really secondary. If your system/acceptance tests can't find bugs you are screwed anyway. And I find code written mindfully, one step at a time, has very few bugs. Unit tests are just one definition of a "step." You can use the orignial story you are implementing as a step as well. I use unit tests more as a mental focussing device while developing, like Zen Archery, than for the actual tests. After development unit tests are very useful in making sure code doesn't break. So I am not saying unit tests aren't useful. I just don't think they are the real reason behind why TDD generates working code. With a clear well functioning focussed mind we generate working code. But getting into that state is hard.

Writing comments simultaneously with all other aspects of development deepens your mindfulness because you are thinking about everything at once. All the interconnections are present in your brain because you are explaining the intent behind what you are doing.

There's a saying that you don't know something until you teach it. Comments are teaching what you are doing to someone else. When you are writing comments you must generate the thoughts to teach, to explain to someone else the intent behing what you are doing. It's very difficult to make a coding error when all this context is hot in your mind.

I'll go back and forth between documenting, testing, and coding. I'll let the problem dictate what happens when as I am working my way through solving the problem. Saying testing should always come first is too simple a rule and I think misses the larger point about software development.

Software is ultimately mind stuff. Using our minds better is the real methodology.

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

Include Statement Documentation

• ISA - this class inherits from the class in the include file.
• HASA - this class contains, that is has as a member attribute, the class in the include file. This class owns the memory and is responsible for deleting it.
• USES - this class uses something from the include file.
• HASA-USES - this class keeps a pointer or reference to the class in the include file, but this class does not own the memory.

Example

#ifndef XX_h
#define XX_h

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

Block Comments

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

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

}  // End Block1

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.

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!

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.

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.

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

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

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.

Using Design by Contract

1. DO NOT PUT "REAL" CODE IN DBC CALLS.. Dbc calls should only test conditions. No code that can't be compiled out should be included in Dbc calls.
2. Every method should define its pre and post conditions.
3. Every class should define its invariants.
4. Callers are responsible for checking preconditions. An object may not and is not required to test for assertion violations.
5. Method pre-conditions should be documented in a method's interface documentation.
6. Pre-conditions can be weakened by derived classes.
7. Post-conditions can be strengthened by derived classes.
8. Every Class Should:
   1. Develop its class invariants.
   2. Code its invariants and call them in its operations.
   3. Document its invariants in the class documentation.
   Yes, this takes a lot of work, but high availibility is the system's __primary goal__, meeting this goal requires a lot of work and effort by each programmer.
9. Every Method Should:
   1. Develop a list of exceptions.
   2. Develop operation pre-conditions.
   3. Develop operation post-conditions.
   4. Code the exceptions, pre, and post conditions.
   5. Document the exceptions, pre, and post conditions.
   Yes, this takes a lot of work, but high availibility is the system's __primary goal__, meeting this goal requires a lot of work and effort by each programmer.

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

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=(const XX& from);  

// OPERATIONS                       
// ACCESS
// INQUIRY

protected:
private:
};

// INLINE METHODS
//

// EXTERNAL REFERENCES
//

#endif  // _XX_h_

Required Methods Placeholders

Ordering is: public, protected, private

• programmers should care about a class's interface more than implementation
• when programmers need to use a class they need the interface not the implementation

LIFECYCLE

OPERATORS

OPERATIONS

ACCESS

INQUIRY

#include "XX.h"  // class implemented


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

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

XX::XX()
{
}// XX

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

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


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

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

}// =

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

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

#ifndef filename_h
#define filename_h

#endif 

#ifndef namespace_filename_h
#define namespace_filename_h

#endif 

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

Method Header

  /** Assignment operator.
   * 
   *
   * @param val The value to assign to this object.
   * @exception LibaryException The explanation for the exception.
   * @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);

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

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

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

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

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

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 .

Minimize Inlines

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.

Do Work in Open

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

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

Thin vs. Thick Class Interfaces

The two extremes are thin classes versus thick classes. Thin classes are minimalist classes. Thin classes have as few methods as possible. The expectation is users will derive their own class from the thin class adding any needed methods.

While thin classes may seem "clean" they really aren't. You can't do much with a thin class. Its main purpose is setting up a type. Since thin classes have so little functionality many programmers in a project will create derived classes with everyone adding basically the same methods. This leads to code duplication and maintenance problems which is part of the reason we use objects in the first place. The obvious solution is to push methods up to the base class. Push enough methods up to the base class and you get thick classes.

Thick classes have a lot of methods. If you can think of it a thick class will have it. Why is this a problem? It may not be. If the methods are directly related to the class then there's no real problem with the class containing them. The problem is people get lazy and start adding methods to a class that are related to the class in some willow wispy way, but would be better factored out into another class. Judgment comes into play again.

Thick classes have other problems. As classes get larger they may become harder to understand. They also become harder to debug as interactions become less predictable. And when a method is changed that you don't use or care about your code will still have to be recompiled, possibly retested, and rereleased.

/*virtual*/ void
Class::method()
{
}

/*static*/ void
Class::method()
{
}

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 an Agile methodology to your liking. For more information see http://www.possibility.com/epowiki/Wiki.jsp?page=agile.

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.

For more information see http://www.possibility.com/epowiki/Edit.jsp?page=UserStory.

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.

For more information on code reviews please take a look at here. You'll find a lot of information on justifying code reviews if you are having troubles instituting them and lots of suggestions on how to conduct them.

1. Subversion - a free, popular, and well featured system.
2. Perforce - a not free, popular, and very solid system that scales beautifully and just works.
3. Clear Case - a not free, popular in larger corporations, and requires a dedicated admin team, yet you can accomplish a lot with it.

There are many other options out there. It doesn't matter which one you pick as much as it does that you pick one and use it.

1. Jira - a full featured and reliable bug tracking system. It works best when combined with Confluence, their wiki product.
2. Bugzilla - a free product that is functional and widely used.

As for source code control systems there are many available bug tracking systems. It's more important that you use one than which one you use.

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.

I've written up my hard one advice for using wikis at Getting Your Wiki Adopted.

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.

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;

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 (...)
   {
      case 1:
         ...
      // FALL THROUGH

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

      default:
   }

   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;

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 probability of declaring a variable when you actually mean to declare a pointer.

   DWORD       mDword
   DWORD*      mpDword
   char*       mpChar
   char        mChar

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

In .h file:

class PopcornPopper
{
public:
   virtual void Pop(void);
   static PopcornPopper* Singleton();
};


In .cpp file:

/*virtual*/ void 
PopcornPopper::Pop(void)
{
}// Pop

/*static*/ PopcornPopper* 
PopcornPopper::Singleton()
{
}// Singleton

Document Null Statements

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

Create One Exception for Each Library