Tips and Tricks of the C++ Professionals

A different name for this book was considered:

Tips and Tricks of the C++ Masters

Instead, this book is for the professional developer of large scale C++ programs. Its about standard practices, regularity, simplicity, and correctness.

Experience can be a difficult task master. Hopefully this book can help the reader avoid a few painful lashes.

This book is not a tutorial of the C++ language. Rather, it addresses approaches to successfully using existing C++ compilers to develop real world programs in a professional manner -- and, hopefully, as quickly and as painlessly as possible. The following chapters are organized such that they can be easily used as a reference, but also contain sufficient explanatory material to justify the advice found in them. Each chapter begins with a very quick summary of what is said in the chapter -- usually as an indented list of suggestions. The remainder of each chapter expands and justifies each.

The remainder of the book is arranged according to this broad outline:

Become a C++ expert

A discussion of some of the important skills professional programmers need to develop.

Adopt good habits

Specific C++ implementation habits that will simply development when working in large teams.

Speed: writing fast programs

Tips for improving performance.

Designing Classes

Tips for class design that improve maintainability.

Tricks of the template masters

Using templates to simplify code maintenance.

Write no code before its time

This chapter addresses the issues to be considered before coding actually starts -- such as

• what is supposed to do?
• what platforms is the code supposed to run on
• how are errors handled

Compilers, librarians, and linkers

A discussion of the wierdnesses to experienced using the primary tools of software development. Particularly, unexpected and annoying behaviours of the real world programs implementing the ivory tower descriptions of these tools.

• Understand the language!
• Practice, practice, practice!
• Read good books on programming
  • Bjarne Stroustrup's: The C++ Programming Language, 3rd edition.
  • Scott Myers: Effective C++
  • John Lakos: Large Scale C++ Development
• Learn to use your tools
  • Learn your editor -- you'll use it a LOT
  • Use a good CM system and be expert
  • Learn purify, quantify, purecov
  • Learn a good text processing script language
• Learn the STL and follow its design patterns

Objected oriented thinking can be extremely helpful in system design and analsysis and should be well understood by professional programmers -- particularly for application level class designs. However, focussing only on object oriented methodology can lead to a failure to use some of the more helpful features of C++ -- particularly templates and meta-object construction.

That is, C++ provides OO tools for high level program artifacts, but it also provides its own particular specialties to assist in the day to day mechanics of development quite apart from OO methodology. Like many complex things, there are several layers in which C++ can be understood. The following paragraphs discuss these ways. You really only need to understand C to use this level. This level of understanding gives you better compile errors, but will not allow you to take advantages of the C++ features that make it worthwhile to use.

Features will begin to notice at this level include:

C++ complains more about questionable practices, so it helps you avoid problems.

At this level, you need to start learning to do without macros. Templates, inline functions, and reference variables (used as function arguments) almost completely eliminate the need for C macros. Note that const variable declarations and enum's remove the need for #defining constants. For example:

enum constants_list
{
  constant_name_1=constant_value,
  constant_name_2=constant_value_2
};


Further, the member access declarators let the class designer prohibit access to methods not part of documented interfaces.

Further, constructors and destructors help guarantee that package specific design assumptions are enforced. That is, when a class is designed, object member variable values are assumed. In plain old C, without constructors and with no power to prevent the calling of the wrong functions, these guarantees are impossible to enforce.

The first step in true object oriented programming is understand encapsulation of data and methods in classes. The next is to learn to design a class' methods so that they guarantee the internal state of the data in the class objects at all times and then to prevent access by outside functions which might not obey these state guarantees.

The C++ language does not force object oriented programming on the developer -- it is up to the developer rigorously attend to this paradigm. Collections of class objects can be implemented in numerous ways. Some standard container paradigms are: vectors, stacks, lists, associative arrays, etc. Templates let you instantiate behaviorally consistent but class specific collections of objects in an efficient manner. There is an ANSI standard set of container classes, the STL (Standard Template Library). Each compiler also provides its own approximation to the STL. These are typically not 100% compatible. You can make your own container templates and port them but doing so is by no means a trivial task. It requires that you understand how new and delete really work. It requires that you understand the assignment and copy constructor logic, etc. You really need a good understanding of pointers, references, inline functions, and operator overloading to build an efficient container class. Here, you build data structures that emulate the atomic objects. For example, you might want to implement a representation of the time that can be treated as an integer in that you can assign an integer to the time and vice versa. You would want to be able to use the time on the right hand side of operator= to perform calculations involving integers and time values. Further, you probably want a character string representation, eg "12/28/57-11:03pm". So, you'd want to be able to write expressions like this:

1. String concatenation expressions:
   
     A = B + C + D + E;

   If this were implemented directly, you'd get
   
     concatenate B with C and store the result in T1
  concatenate T1 with D and store the result in T2
  concatenate T2 with E and store the result in T3
  store T3 in A

   A more efficient approach is to define the string::operator+ to return not a string but a description of the string. That is, instead of T1, T2, and T3 being strings with the concatenated values in them, they are actually data structures that describe the components that make them up:
   
      T3 contains a pointer to T2 and to E
   T2 contains a pointer to T1 and to D
   T1 contains a pointer to B and to C

   Then make the string::operator= know how to convert a string description into a string and store it in A efficiently. It must also free up any memory used to hold the description.
2. Matrix arithmetic operations are similar. Instead of a having
   
      A = B * C * D * E;

   evaluated using 3 intermediate steps, it is much faster to have a matrix multiply by a list of matrices function and have the matrix:operator* produce the list. The matrix::operator= then knows how to invoke the multiply list function and save the results.

There is no substitute for practice when it comes to software development. The more often you deal with your editor, the compiler, its error messages, and porting, the easier it will be to do these things. But don't play in the production code base. Do these things in your own personal directory. If an idea pops into your head, create a small C++ source file to check it out. Then port it to all platforms available to you. A good configuration management system is essential to the success of any production software product. For individual developers, the most important benefit it provides is the ability to get back the code you used to have after you have screwed it up. This ability, to run back time, as it were, allows you to edit your code without fear. Many developers are rightly afraid that they will mess up the product and spend a lot of time and effort getting it fixed. A good CM system will help you overcome the irrational aspects of this fear -- you can always find out from the CM system who did what -- and how to undo it.

A good CM system is not necessarily cheap, nor is it necessarily easy to use. Just because you can get one, like CVS, for free, does not necessarily mean that it is a good system. Whatever system you use, be an expert with it. If you don't become an expert, you are like to be more afraid of it than you are of breaking in the code base. Learn the CM system and become and expert.

In particular, you should learn how to make branches and apply labels for your own private use. Once you have learned to branch the code base, you can make any change you want with impunity. If you completely screw it up, just delete the branch -- or simply ignore it and go back to the 'standard' branch. Clearcase, for example, makes this very simple. It is a bit more complex with CVS. Because people are habitual in nature, we sometimes do the same wrong thing over and over again in dozens of files. Perhaps your organization established standards and practices that later turned out to be a bad idea. The ubiquitousness of a mistake should not be an impediment to fixing it.

Don't be afraid to edit your code using some text processing script language. The standard unix tool, sed, is relatively easy to use for simple textual substitutions using regular expressions. For more sophisticated changes -- or substitutions that span multiple lines of text -- you'll have to use perl.

If you have a good CM system, you should not be afraid to sweep through every file, check it out and change it with a script. If your script messes up a file, just get back the prior version and make the needed changes by hand. Even if you don't have a good CM system, you can just copy the files to another directory and do your experiments there.

Often, you can only fix some significant fraction of the code using a script -- perfecting said script to the point where it fixes all the cases might well take longer than fixing the remainders by hand. Thus in many cases, when a script is used there will still be some hand work to be done.

"Algorithms and iterators work so well together because they nothing about each other". -- Andrew Koenig.

(Of course, Bjarne Stroustrup is the giver of the gift!)

In addition to being 'standard', the STL is a great source of programming paradigms and implementation paradigms. Chief among them are 'algorithsm', 'containers', and 'iterators'.

iterator

The normal iterator for the container.

const_iterator

The iterator that only points to constant data

reverse_iterator

An iterator which iterates 'backwards'.

const_reverse_iterator

The const version of the reverse_iterator

output iterators

Output iterators only really support dereferencing and assignment:

• operator*
• operator++

A good example is the std::ostream_iterator. In that case, increment operator causes the data to be physically written.

Note that output iterators cannot (conceptually at least) be copied -- although they can be returned from functions. You can't save them in temporary variables and use the saved value later.

input iterators

Similar to output iterators, this form also only performs operator* and operator++. The same restrictions about saving input iterators applies here.

A good example, is the std::istream_iterator.

forward iterators

Forward iterators have all the features of input and output iterators, but they do allow you to save them and use the old value.

bidirectional iterators

A bi-directional iterator is the same as a forward iterator but it also supports operator--

random access iterators

Random access iterators support all the features of all other iterators and also add

• the array index operator, operator [] ().
• iterator subtraction
• adding/subtracting ints to iterators

Further, the assumption is that all these activities are O(1).

When writing your own template algorithms, try to do the following:

• Write your new algorithms according to standard paradigms -- or as Stroustrup suggests: "prefer the standard to the offbeat" .
• Understand the iterator classes and make sure that you use the least functional iterator that does the work. For example:
  • don't use the iterator's operator + () unless you really have to. If you are going to only add one or two, just use the operator ++ (). Ditto for the subtraction operator.
  • don't use the iterator's operator -- () unless you have to.
• If you feel that you need to implement your algorithm to get the maximum efficiency out of random access iterators -- which do support pointer arithmetic, consider writing two algorithms -- one for random access iterators and another for all others. Theoretically, you might need 4 versions -- one for random access iterators, one for bidirectional iterators, and one for forward iterators (this will handle the input and output iterator categories as well -- usually).

  When you decide to provide multiple instances of your algorithm, use 'routing' template function to select among the alternates. See the distance overloaded function example below.

An auto_ptr is particularly useful in some important cases:

• local variables initialized with operator new
• class members that own memory
• functions returning new'd up objects which must be deleted by the caller.

Here is a simple example of an auto_ptr's use:

Only one auto_ptr object can own a given piece of memory. Whenever the copy constructor or assignment operator of the auto_ptr class is invoked, it takes ownership away from the source variable. Consider the following code:

It is tempting to think that other_function should be declared like this if it were to take ownership of the pointer:

The automatic destruction of the temporary variable will destroy the object refered to by parameter p. This is not likely to be the desired result -- and it will be very hard to debug without using purify.

In general, it is better not to use auto_ptr as function parameters -- although function returns are a very good use:

Finally, while it is tempting to use a container of auto_ptr's to automate the process of destructing objects whose pointers are stored in the container when the container is destroyed, this won't work very well because of the copy constructor logic of auto_ptr does not in fact make a copy. This of course violates a basic principle in the design of STL containers and they cannot be expected to work correctly using auto_ptr as template parameters.

Instead of using, say a std::vector< auto_ptr< t > > which will automatically destroy the T's owned by the container, derive from the vector and make the derived class' destructor do the freeing:

Unfortunately, at this point in the history of the STL, the auto_ptr class is implemented/declared in different ways on different compilers. The HP compiler, for example, requires that the strict ansii compatibility compile option (-AA) be used event to use auto_ptr -- and even then it is very selective about non-trivial uses.

The following code will likely work even if the runtime library version causes trouble. This code puts its auto_ptr definition in a namespace, alt_tools. Doing this is not a requirement, and will not work unless namespaces are supported. Simply remove the namespace wrapper if needed.

Due to the unusual nature of the auto_ptr many uses and bugs in various compilers, there is some ugly casting away of const that cannot be avoided. But they mean that care must be taken with this auto_ptr's use (for example, don't use it as a function parameter's type).

• Play in your home directory, not the code base
• design all software as if it were a library
• Keep it simple stupid
• Don't imbed calculations in your UI layer -- they are too hard to test there.
• Use maximum warning detection (strict Ansi too)
• Test early and often
  • regression tests
  • test coverage analysis
  • memory misuse detection
  • The hard way -- heapwalk
• adopt and stick to a naming convention
• Port early and often
• Use a CM system; commit and label often
• Avoid macros, prefer inline functions
• Make your destructors work correctly!
• Don't do things half way
• Learn from the STL
• Static initialization order depencency
• Limit the use of 3rd party library symbols
• Use nested typedefs to shorten and standardize names
• when writing templates, add code to check for erroneous template parameter types

For example, if you decide (as I once did) that it would be really cool to write your own operating system, don't jump at the chance to write your first operating system as part of some production product development cycle (as I did). Instead, do this in your own private directories -- and stick to traditional operating systems until you perfect yours (and can convince other people to use it by force of argument rather than by shoving it down their throats just before leaving them to debug it when you go on to the next project where you get to write the next cool thing and stick it in the production code base).

Practice is good, but don't practice in the code base -- that is for work, not play. One of the advantages that are found in the development of good library modules is that they are easily tested. Unfortunately, a lot of application programs quickly lose this ability due to complex internal interfaces that do not lend themselves to easy testing. For example, there may be many functions in a program which were written with the assumption that they will be used but at any given time the program never call them.

The fact that these functions have never been tested will be lost and when program is changed and the code finally does call the neglected functions they will malfunction in strange ways. This often leads developers to tear their hear out in frustration with the famous exclamation, "How did this ever work?!" In this case, it didn't but no one knew.

The principle problem here is that the program was thought of as a sand pile rather than as a building constructed of floors -- each of which could have been individually built and tested. But this view is simply a matter of choice on the developer's part. There is no reason that the "application" cannot be a thin layer of glue logic on top of an existing set of libraries whose interfaces are clearly documented and well defined and easily tested early.

Another important advantage of library design is that it encourages re-use. Re-use is a complex thing that is best accomplished by practice. The more you try to make the code re-usable, the more often you will be successful at it. People writing "programs" rather than libraries rarely pay attention to the usability and documentation details that make or break re-usability.

The pursuit of re-usability is to some extent like a moral philosophy. At any given point in time it might not be in one's short term best interest to adhere to a particular precept of the philosophy, but the belief is that, if done consistently, one's long term best interest will be ultimately served by conformity.

Of course, deadlines and ill considered promises interfere with perfect adherence to the goal of writing all code to be re-used. Further, in many cases, code is known to be discardable. In these situations, it is still valuable to follow the general outline of creating all programs as a collection of libraries which are glued together by the main program. This design makes it easier to understand the parts of the program -- even if they were hastily constructed. It also makes it easier to write a new library that replaces an old buggy one!

In programs that are not constructed as collections of libraries, there are often interconnections between disjoint parts that are difficult to break or even understand. Even worse, some of the interconnections are not physical so much as accidental. For example, if a function never returns a number greater than 10 during its initial implementation phase, a consumer of this function might mistakenly assume that it never will and forget to test for this condition. Part of design code in libraries is the act of documenting the behavior. Library design makes the need for this documentation more obvious than is often found in "application" code where all the source code is bundled together for easy viewing and misunderstanding. Human beings cannot remember to always do the right thing, but computers can help -- use automation to make sure that mistakes are either prevented or caught early.

Products, of course, should be built using either Makefiles, scripts, or IDE project build instructions. This is a good place to automate the detection of the use of prohibited symbols or coding practices -- if such can be quickly detected using grep, perl, or other fast text processing language. Just add additional rules to search the code during build time for violations. The following paragraphs describe some approaches to using the compiler to help prevent problems. Also, see Early Error Detecton in the templates chapter. The principle advantage of C++ is that it provides automatic behaviors such as the firing of constructors and destructors. A standard automatic way of making sure that allocated resources get freed is to declare a variable of a special type whose destructor performs the release. That is declare an object that represents the allocation of a resource. When the object is destructed -- if not before -- free the allocated resource. Here's an example code fragment:

Handles are similar to auto_ptr's in that destruction is guaranteed (almost) but differ in that there can be more than one handle to a heap packet -- not just the one allowed by an auto_ptr. Unfortunately, there is no standard 'handle' as of yet. The following paragraphs describe one possible implemenation.

Typically, a handle is a class object that is used like a pointer. However, its implementation is such that there is both a pointer to the 'handled' object, but also a reference count. Creating a handle to a given physical object increments the reference count associated with that object. Destroying the handle decrements the count. When a handle's destructor fires, and the reference count decrements to 0, then the object refered to by the handle is destroyed.

In a single threaded application, handles are a clear win because they prevent memory leaks (mostly) in cases where ownership of objects must be shared between multiple code fragments or classes. However, in a threaded situation, where multiple threads may share control of an object, and thus its handle's reference count must be thread locked, signficant performance penalties can occur. Multiple copies may well be the best solution in a multi-threaded environment. Performance analysis tools may be required to understand one way or the other.

The construction of an auto_ptr object looks basically like this:

Only developers can write 'white box' tests because they know how the code works. They have to think about the things that can go wrong given the architecture of the code and make sure that tests are written that detect and report such malfunctions.

The QA team should only be writing 'black box' tests. That is, tests written using only properly documented functions that the user is specifically paying for. If the QA team writes tests that rely on undocumented features, it will be very difficult to get rid of features -- and likely be expensive to maintain them -- even though the customer never wanted them. Only developers can write tests that validate the test coverage levels on a per line of code basis. It is extremely important that code be tested to a level of at least 85%. That is, that 85% of the lines of code have been executed during the course of a suite of tests and that these tests do in fact actually operate on real data -- and most importantly that the code does in fact give the right answers. There are several tools that can help you determine if your tests have achieved at least 85% coverage:

• purecov by IBM/rational
• tcov on linux
• pcov on other unix machines
• covtool -- see covtool.sourceforge.net

1. Prepare a special version of your executables and libraries that will produce information about the lines of code that have been executed as the program runs. The technique for doing this varies from tool to tool.
2. Run all your tests using these instrumented executables.
3. Aggregate the coverage information produced by all the various runs.
4. Use the tool to make a report of which lines of code you have executed and which you have not.
5. If you have not achieved at lest 85% test coverage, add more tests and repeat the above.

There is a share ware program that works roughly like purify that is avaialable for linux: valgrind. It does not have all of purify's features but since you can download it for free in some settings, it can give you a taste of how valuable purify can be -- and valgrind can be quite helpful in its own right.

Using purify correctly is somewhat complex but if you learn it and set up regular regression testing using it, you will find that the payoff can be very high. Imaging trying to catch a random memory misuse that only occurs after 12 hours of program execution when the program's memory size has grown to 20 gigabytes or so -- how would you go about it? You get a machine loaded with 56 GB of ram, purify the executable, and let it run for 2 weeks until it prints the first message: memory misuse caused by line 102 in file "bla.c" with the following calling stack ....

Luckily most problems can be duplicated quickly, with a little work, but even then, purify can often point you to the exact line of code that caused the problem and describe the circumstance in such detail as to make it easy to fix. If you are unable to use purify or valgrind to help you detect memory bugs, try using the memory allocator's internal tables to detect when its memory chains are broken. Sometimes when bugs envolving randomly writing all over memory. The memory allocator has pointers throughout your heap space. The random writes may hit your memory allocator's chains. The malloc header file may well describe how to iterate over the chains and detect bad links. The Microsoft compiler provides a function called heapwalk to help you do this. Other platforms do not.

If you are using a 3^rd party memory allocation tool, it might might have special features.

Another 'doit it youself' technique is to superseed the global ::operator new. This function basically just calls malloc and returns its return value. You can intercept these calls to new and add some extra space at the beginning and ending of the heap packets requested from malloc.

You fill these packets with known values in ::operator new. Then, during ::operator delete (), you check to make sure the correct values are still there. If they are not, then you know that your program has misbehaved.

If you try something like this, remember the following:

• the size parameter to operator new can be any number
• memory can only be allocated in fixed size chunks -- usually multiples of sizeof(double)
• adding space to the beginning of the packets must be done in multiples of the chunk size or you will get memory crashes caused by your implementation of operator new ()

As annoying as it may sound, if you are working in a porting environment, you have to take into account the mistakes of the compiler vendors and those of the vendors of any third party libraries.

One of the most tedius problems encountered is the use of the preprocessor to define names that you want to use for something else. For example, the name 'unix', as well as 'UNIX', and 'Unix', are highly likely to be #define'd to be '1' on some system or other. This means that you cannot define a class, a macro, a function, or a variable named simply 'unix', or 'UNIX', or 'Unix'.

Sadly, there is a myriad host of simple computer science related words that should not be used for the same reason. There is no fixed list, but a simple rule to follow is this: do not use any simple english word that might be computer science related. Instead, used underscores to separate word fragments. For example, instead of using 'unix', use 'unix_flag', or some other such thing.

The compiler vendors are supposed to put leading underscores on their #define's -- so you should never define a symbol that begins with an '_'. For example, don't use '_unix', nor use '__unix'. Nor '_bob', '_srikanth', etc. Leading underscores belong to the compiler vendor.

Nesting your symbols in namespaces, functions, and classes does not help if the symbol is defined in the preprocessor.

The only work around to this problem if you have unwittingly caused it is to put #undef's in your source somewhere after including the header file defining the symbol causing you trouble. For example, the stdio.h headef file defines the name 'fileno()' as a macro. If you had large body of code and you could not easily change your own variable name, fileno, to something else, but you absolutely have to include stdio.h somewhere where your own fileno is defined, you can do it like this:

Developing and sticking to a standard naming convention can greatly ease your porting burdens -- and improve the understandability of your code even if you aren't porting. Here is a simple example of such a naming convention:

• Do not define any name that begins with a leading underscore.
• Avoid #define whenever possible -- prefer typedef's, inline functions and const variable's instead.
• Avoid #define, symbol, class, and variable names that are simple computer science terms or operating system names, etc -- use longer names separated by underscores instead.
• Whenever possible, do not pollute the global namespace -- that, put your symbols in namespaces or nested within classes.
• The standard library uses all lower case identifiers, so projects can use mixed case names for their own purposes. Here are some example choice:
  • Class, typedef, and enum type names could be distinguished by making them mixed case: Some_Class, or SomeClass .
  • Namespace, variables and function names can be lower case because functions are easily distinguished by the '()'s that immediately follow their use: fred_is_bad, func(), etc.
  • global or namespace constants, enumeration values, and #define'd constants can be all upper case with separating underscores.
  • class members can have a trailing underscore: member_one_.
• Source code file names should be limited to characters that are known to port to all target platforms of interest. This means that you should in general use the unix file pathname syntax -- ie with a '/' as a separator rather than the '\' (backslash) character in any #include directives. This is because the microsoft compiler will recognize the '/' as a path separator but the unix compilers will not recognize the backslash ('\').

• When writing #include directives, it is generally inadvisable to use fully qualified pathnames. No to versions of the same operating system / compiler combination will guarantee continuity of the names of directories where standard tools can be found. Usually they are consistent but there is no guarantee. Rather than imbed specific pathnames in your source code, rely on the compiler's -I parameters to help you find the code.
• Also, the use of double quotes as opposed to angle brackets is a bit tricky. Some compilers treat the double quotes as being exactly like the angle brackets and some (Borland) treat them differently. The difference has to do with the start of any search for the named file. G++ also seems have unusual features in this regard. It is best to avoid the double quotes unless you understand the porting implications for the specific platforms of interest.
• To reduce the chance of a name conflict between header file names, it is advisable to refer to project header files using the directory name as well as the file name. This requires that when you compile, the -I directives be set up correctly to make it work. So, instead of using this:

  #include <myfile.h>

  You would do something like this:

  #include <my_project/myfile.h>

  This prevents trouble caused when 'myfile.h' is defined in some third party library as well as yours.

  Note that this approach can also reduce the number of -I statements needed by the compiler on a large project. For example, suppose your project source code tree looks like this:

  main_dir
    lib1
        header1.h
        header2.h
    lib2
        header3.h
        header4.h
  

  Instead of using using two -I statements on the command line to the compiler like this:

  -Imain_dir/lib1 -Imain_dir/lib2

  You could just use one:

  -Imain_dir

  This means of course that the header files would have be included using the directory name fragment:

  #include <lib1/header1.h>
#include <lib1/header2.h>
#include <lib2/header3.h>
#include <lib2/header4.h>

• In general, header file names should have some file name extension, preferably .h. Unfortunately, writing 'make' rules that properly handle all the cases is made much more complex if you leave the file name extension. Also, Microsoft Windows and most browsers rely on the file name extension for type information.

Here is a short example source file obeying these rules:

   #ifndef SOME_CLASS_DEF_H
   #define SOME_CLASS_DEF_H 

   extern const int MAX_DOG_COUNT;

   namespace our_company
   {
     void 
     some_function (int some_parm)
     {
	float some_variable = some_parm;
     }

     struct Some_Struct
     {
       typedef std::vector Vector;

       Vector vec_;

       Vector const &vec () const { return vec_; }

       enum Constants
       {
	 ONE=1, TWO=2
       };

     };

   };

   #endif

Porting your code to other compilers can help detect such things with little work on your part. Other compilers will have had other developers write them. These other developers will have made different choices about warnings and error detection. If you port your code to a variety of platforms, one of them will likely give you a good error message about the problem you have unwittingly created. Therefore, it is wise to start the porting process as early as possible -- rather than leave it to the end.

Porting the code envolves both getting it to compile and also running your regression tests on that platform. You should do both of these things early and often. When the time between a code commit and the discovery of the breakage is large, it becomes more difficult to remember what you did that might have caused the problem. Not all porting errors appear as compile errors -- some are just bugs. Detecting a bug on a porting platform long after the author created it is very tedius.

Some porting difficulty is caused by floating point numbers -- you will get minor differences in roundoff or stream output behavior. These differences are not necessarily bugs -- but they might be.

One way to work around such 'allowed' differences between operating system behaviours -- particularly with respect to floating point numbers is allow different results on different platforms based on specific test results on specific platforms. You should be wary of just ignoring the test results on a platform though. You just need some way of officially stating that 'test A works differently on platform P than on platform O'. Don't let these differences between platforms dissuade you from automted test mechanisms -- use scripts if you have to enable automated testing for all platforms.

• assuming that pointers are the same size as integers or longs -- there is no guarantee that this is so.
• assuming that integers and longs are the same size
• using platform specific behaviours
  • header files that exist on only one platform
  • run time library functions that exist on only one platform
  • treating vector<T>::iterator as it if were simply a pointer not a full function class object (which cannot be converted directly into a pointer!)
  • forgetting to avoid symbol names that might easily be defined as macros on some other system -- such as 'unix'.
• different compiler revision levels on different platforms means that some features of the language have to be avoided
• assuming that all local and global variables obey the worst case memory alignment criteria. For example, the following code may crash and it might work fine: void function() // bad implementation { char bill[sizeof(double)]; double *tom = (double*)&bill[0]; *tom = 1.9; // CRASH may occur here }
  Here is a slight change that will gaurantee the proper alighment: void function() // bad implementation { union { double tmp; char bill[sizeof(double)]; }; // unnamed double *tom = (double*)&bill[0]; *tom = 1.9; // Will not crash because bill // is aligned the same as tmp }

A common mistake is to make a class object with a variety of data members and functions but which does not make guarantees about the state of these data members. You do not have a class, but rather a named 'pile' in this case. And just like a pile of sand, as you add more grains to the top, you will eventually see a catastrophic collapse as all the sand grains slide to the ground.

Don't make piles of data. C++ classes should be objects whose internal states are guaranteed at all times which makes sense. Here are some general guidelines for completeness:

• Watch the ownership of new'ed up memory! This isn't java -- you must take responsibility for memory which has been new'd up.
• Make your destructors work. You might want to use auto_ptr's to simplify your life.
• If your class has any pointers which refer to memory which has been newed up in the constructor or which the class has been given ownership thereof you are likely need to create all of the following:
  • copy constructor
  • destructor
  • assignment operator
  • comparison operators (if needed)
  
  Failure to make these things when needed is silent but deadly -- it will come back to haunt you. This is an easy thing to look for in code reviews: if you own memory, you need all the above.
• When writing templates, make add template type constraints to help clarify errors that your poor user is likely to get. See below.


// at file scope

extern int fred();
int bill = fred();



// at file scope

#include <class.h>

Class varname; // this is a static init


There is always a special case that will work, for a few releases of yor product at least, but in the long term, after newly hired people have taken over maintenance of your product, static initialization will eventually come back to bite you for reasons described below. It will be safer if you find a way to initialize all your program variables after main() begins executing. Typically class objects should not be allocated statically because of their constructors -- but you can allocate static pointers and fill those pointers after main() begins executing. In the example from the prior section, a declaration of an external function, fred() is made, and a variable name bill is defined. Also, before main begins executing, bill is initialized with return value of fred()

This is a nice feature, but it leaves you open for some vary nasty shocks. What if fred() requires that bill be properly initialized before you call it? It will return an undefined value -- which may be annoyingly constant until you port to another platform and then you will get nasty surprises.

You might think that an intelligent developer is not likely to make this mistake. However, experience shows this not to be true. And worse, it is not one developer that is involved in an error of this form. The original author of fred() may well know not to use variable bill as party of its implementation -- but subsequent maintainers may not know that bill is initialized by calling fred() and may unwittingly make fred() dependent on bill -- perhaps even accidentally. Consider, if a change to fred() envolves a call to function tom() and the developer who modifies fred() did not write tom(), how will he know that tom() uses the global variable bill?

There is no solution to this problem -- you just cannot write code that depends on a global variable safely if the function is used to initialize the variable or any other variable envolved that variable's initialization. Luckily bugs of this form are easily caught. Unlike the obvious order dependency bug described above, other, more subtle order dependency bugs can creap into your statici intialization logic. Suppose your program has two global variables which are both statically initialized and further suppose that the second variable's intialization requires that the first be initialized it can be initialized correctly. Will this situation work? Here is a concrete example. Consider the following files:

File h.h

extern int g ();
extern int f ();

extern int var_one;
extern int var_two;


File one.c

#include <h.h>

int var_one = f();


File two.c

#include <h.h>

int var_two = var_one + g();


This program will work correctly one if var_one is statically constructed before var_two. That will only happen if file one.c is linked into the program before file two.c.

In a program with only two object modules, this is easily controlled. Typically, the linker places the objects into the module in the order in which it encounters them. All you have to do then, is make sure that file one.c's object module appears on the command line to the linker before file two.c's object module. But what if file one.c and file two.c are in libraries? The linker has no way of knowing that it should put file one.c's object first. It might put it first, and it might not depending on a large number variables. Further, different linkers on different platforms will make decisions differently -- and thus the code might work one platform in one release, but may not work on other platforms in that same release -- and may not work on any platform in a different release. Here are some approaches for forcing initialization after main():

• You could make all variables that require function calls to initialize them be pointers -- that means all global variables and static class objects. You then publish the fact that before using your code, the customer must call some initialization function you provide -- which will fill those pointers.
• You could make a global linked list of 'stuff to do' and have main() execute code to 'do' all the stuff. This of approach requires that you create static initalizations that append the 'stuff to do' for each file into the global linked list. You also have verify that the global linked list gets linked into the exeuctable first.
  
  This may not seem like a safe solution -- given all the problems documented above, but the fact is that it is possible to get a single object module linked first -- you just can't get a bunch of them linked first. Besides, it is better to have your main() program call a single function to handle all initializations everywhere than to have a long list.

• don't do things you don't need to do
• don't leak arge amounts of memory
• reserve threads for very special situations
• The "Big O" -- understanding algorithmic complexity
  1. STL container overview
  2. using std::vector
     • Fastest 'find' but slowest insert
     • Pre-allocate space if you can
  3. using std::list
  4. using std::map
• use the throw() keyword when you don't use exceptions
• virtual function calls
• maximizing the chance of inlining
• Malloc performance and operator new

O(1)

Order 1. When something takes 'order 1 time' it means that the cost for accomplishing the task requires a constant amount of time -- which is to say, 'outstanding' from a complexity viewpoint.
There are no O(99)'s or any other O(constant number) -- O(1) suffices to describe this case. Even zero time, when no work at all needs to be done, counts as O(1).

O(ln(N))

When N things are available to be processed, the cost for actually doing the work is only logarithm(N) -- which is to say 'great' because ln(N) (as well as log(N)) is always less than N when N is greater than 1. Whether base 2 or base 10 does not matter.

O(N)

When N things are available to be processed, the cost for actually doing the work is N. That is to say, you have to process all the objects at least once. This is 'good'.

O(N*ln(N))

When N things are available to be processed, the cost for actually doing the work is N * ln(N). That is to say, you have to process all the objects at least once. This is 'ok'.

O(N^2)

When N things are available to be processed, the cost for actually doing the work is at least N squared. Which is to say 'bad'.

O(F(N))

When N things need to be processed, the cost for actually doing the work is N^3, N!, or some other horrifyingly huge amount of time.

Note that because an algorithm if O(1) does not mean that it will be fast. It could be a large O(1). However, O(1) does mean that the amount of data being processed does not matter. Which means that adding a million times as much data does not making the code any slower.

Consider the cost of the following operations on an STL container: first, insert 1 million items, then find each item in a random order. The following table describes the cost (time) required for each step:

The above table is an example of the 'worst case' situation. It is applicable when large amounts of data must be randomly created and searched.

The use of threads may or may not improve the performance or responsiveness of your programs:

• The simple fact of starting a second thread causes malloc to run a lot slower than it did before. If your program makes a lot of small malloc calls (or in this case operator new) a threaded program will spend up to 50% of its total runtime waiting for memory. This is true, even if all threads save 1 are actually waiting for something to do.
• Global variables which are truly shared between threads must be guarded with mutex locks to prevent data corruption. Waiting for access to a variable (both and read and write) can consume a large portion of your program's runtime.

To overcome the above problems: pre-allocate all the memory for the threads, and architect a program so that each thread has its own data to process -- with little or no overlap in access to global variables. However, retrofitting a large application, which was not designed with threads in mind, can be difficult or impossible -- and simply turning on threads may cut your performance in 1/2.

In general, before committing to the path of using threads in an application, verify that it will in fact speed it up to do so. Numerous experiments are generally required for this. These experiments should be done on a multi-processor machine because single cpu boxes will hide certain programmatic bugs. Failure to put mutex locks around accesses to global variables will result in program malfunction much faster on a multiple cpu machine than on one having only one cpu.

It may be advisable to break an application into two programs. One that does not have threads -- but executes commands in serial. The second is threaded and handles i/o such as web transactions which benefit from thread parallelism. The threaded application can martial data and serialize commands to the non-threaded engine (thus allowing it to run a full speed).

An alternative to this draconian separation is to have an executable which is only threaded during certain phases. When performing lots of small mallocs, for instance, thread could be turned off. Then when the memory is allocated, turn threads on. This only works if the threads are all dead though -- not just stopped during the non-threaded periods.

Another problem with threads is that the stack size is generally fixed. Unlikely the primary thread of an application, the secondary thread stacks do not grow as needed. This means that you have to be more carefull with recursive algorithms implemented in threads than in a non-threaded program -- which is to say, that you have to guess correctly about the stack size. Technically, of course, all recursive algorithms can overflow any stack size -- even the program's main stack. However, threads tend to make the problem worse.

Starting threads is faster than launching a whole new process -- but it is not infinitely fast. In really high performance situations, a pool of threads which are already up and running but waiting to handle the next command is likely to give the best results. The threads in this pool might not terminate until the application does.

• container class member accessors and iterator methods
• input/output functions

If these functions are not inline, there will be very noticeable performance impacts compared to implementations where they are because of the very large amount of data being processed (1 megabyte) and there being several function calls per byte.

In fact, in all major implementations, the istream_iterator and the ostream_iterator are not truly inline.

No virtual method gets actually called in an inline manner unless it is declared inline and is referenced using the class member operator (::). In some implementations, the ostream and istream i/o methods are virtual members of a base class -- resulting in at least one true function call for every i/o operation in the calling code.

Luckily, there is a pair of alternate classes that are:

• std::ostreambuf_iterator
• std::istreambuf_iterator

In all major implementations, the std::vector member accessors are made as close to purely inline as possible. Using the inline keyword is not always sufficient to ensure that a given function or class method is in fact inline. The reason for this is that the langauge definition allows compiler vendors to determine that an given function is too complex to inline and in these cases the function is implemented as a static method in all translation units that reference it. Understanding the rules for all compilers is a bit of a challenge. In general the following things prevent inlining on at least one and probably more of the major compilers:

• large functions
• functions with loops (while, for)
• recursive functions
• functions with multiple return statements

For example, suppose a function has a while loop in it -- but it is only used some times by the function, whereas most of the time the function does something very trivial. This code can be split into two functions, one inline without the loop, and the other outline with the loop. Here is an example of the original function:

• if the program allocates a large number of small objects
• multi-threaded applications

• smartheap by MicroQuill
• MTS by NewCode

It is generally inadvisable to use these tools when building a purified executable -- so the build process must provide for ways of choosing the 3^rdparty memory allocator or not in a given build.

The mere fact that a program is compiled in such a way that allows exceptions to be handled forces it to accept a performance degradation of between 5% and 25% depending on the compiler.

Compilers often provide a way to turn exception handling off at compile time. If exceptions are not used in the program, then it will be worthwhile to use this option. However, this might disable use of the STL, etc.

If a specific function does not use the throw keyword and does not call any other functions that do, it can be individually marked as 'not supporting exceptions' by using the following syntax:

Sometimes the bulk of a program does not use exceptions but some small part does. If the part that does use exceptions is invoked from a single function call, or small number thereof, it might make sense to compile that section of the code with exception support turned on -- and never let any exceptions leave -- that is, have the highest level function in the exception handling part of the program catch all exceptions.

If you must live with exceptions and are noticing a signficant performace drop, try increasing the compiler optimization levels. Unfortunately, this may result in compiler bugs and thus some work to find the modules that can not be successfully compiled at higher optimization. Object oriented programming methodologies spend a lot of energy on determining the specific needs the high level object types -- the application objects. This is obviously good in that all requirements should be met and no unnecessary functionality should be included as it merely burdens the implementation without value.

However, the bulk of the C++ classes that get implemented are not high level application objects but rather represent temporary values and other objects not directly visible in the UML, design diagrams, etc. Attempting to design all these classes using design diagrams may provide a low return on the investment of effort.

Further, focusing only on the specific needed features of these many "helper" classes as understood at the time the project is begun can result in program bugs because the objects will be used in ways not conceived up front. The trade off between over design of simple classes and under design will often fall towards overdesign -- simply to eliminate unnecessary debug effort when these classes are used in ways not originally conceived. At a high level, however, the trade off often falls the other way. Even the low level classes need to be implemented completely. Documenting that such and such a feature does not work is not good enough -- people often think that understand code when they don't. When designing classes try to help prevent such errors using one or all of the following:

1. implement all features a reasonable person would expect to find.
2. use the private keyword to force the compiler to complain about misuses.
3. imbed diagnostic code (perhaps only in debug builds) that verifies the internal state of objects is correct (as best you can).

The compiler generates bad code in the event that the class owns a pointer that should be unique to every instance of the object. The compiler won't know this, so it won't copy the objects pointed to, only the pointers -- leaving two objects pointing to the same thing. A key reason that C++ is better than C as a programming language is that it provides for data hiding. That is, instead of simply exposing data members to all callers -- some of which will not be perfect in their understanding of their responsibilities when using the class -- hide the data and provide members to correctly perform all needed activities on that class.

Unfortunately, a lot of code is written that does something like the following:

• hide a data member
• provide a method returning a reference or pointer to the member

Instead of export references to members, export public functions that do all needed things with the members -- and implement them in a way to maintain the class' design assumptions.

Of course, from time to time one might want to export a member reference for speed reasons -- but this should almost always be limited to const references. Consider:

An alternative to inheritence is the use of template algorithms. Templates increase the chance of achieving inline code performance and because of template specialization can actually be more flexible -- in that basic assumptions can, for specific template parameter types, be changed. Of course, templates do not provide the 'is a' relationship that inheritence provides.

That is, a family of template classes provides the same basic functionality as a class hierarchy where the inheritence is private rather than public.

The two approaches are not mutually incompatible, of course. A template class specialization can be designed so that it is derived from a non-template class. For example:

In this case, any SomeTemplate 'is_a' SomeBase object. There are several reasons to design a class hierarchy using templates for the derived classes:

1. mainly to get the 'is_a' relationship
2. but also to get inline speeds rather than pay the virtual function overhead
3. but also rely on the default implementations of virtual methods of the base class
4. to enable all templates to share the same static data members of the base class

• When you write templates, add in template parameter type constraints.
• Port early and often!
• Instantiation models
• Templates make debugging harder
  • So test the heck out of them
  • Use them when needed to keep code simple -- not just because they are cool.
• Understand compiler limitations
  • The 'normal instantiation model (COMDAT)
  • The AIX VA5 variant and its limitations (static objects)
• Use templates to make maintenance easier not because they are cool.
• Avoid const types as template parameters
• Policy template parameters.
• Template specialization, tool of the gods!

Consider the following example:

As you can see in this example, a single line of code that does nothing more than declare a pointer and set it to zero is used to intentionally cause a compile error if the wrong template parameter type is used. Further, the line of code about which the error occurs has only one purpose -- to cause the error. This makes it very easy to understand what the error means. On the other hand, if left it to chance, you might get an error of the form:

Error, file "x.c", line 100: can't construct a Blurb from a Plarf.

• Overloaded template functions
• Passing types as parameters
• Distance algorithm optimization example
• Template class specialization -- and category classes

Templates are normally a mechanism implementing the same algorithms and data structures across a wide variety of data types. Specialization lets you actually have slightly different algorithms based on the types actually used. That is, you get to have it both ways.

There are two types of specialization -- overloaded functions and explicit specialization. Like normal functions, template functions can be overloaded (at least in the compilers conforming to the 1998/09/01 standard -- and most do). Unlike normal function signature overloads, however, overloaded template functions let you apply algorithms to broad classes of types. For example, you could write one template function that applies to pointers, and another that applies only to non-pointers.

Consider the following functions that let you have different algorithms for different data types using the same function name (check()):

In this case, the difference in algorithms is quite trivial: we are just printing different text. However, it is possible using this approach to have completely different algorithms. Here are some example uses of the above functions:

For example, the HPUX aCC compiler, at least in the older versions, will not promote an array name to be treated as a pointer. That is, on older HP compilers, the check(ta); line in the above example will print 'Not a Pointer'. But on solaris, aix, g++, and Microsoft 7.0+, and the Intel C++ compiler it will print 'Pointer'.

Additionally, some older compilers, like HP will produce copious quantities of meaningless warnings about the above code. The warnings are mistaken per the language standard but it will be faster to suppress the warnings using compiler directives than to wait for HP to fix the compiler (;->)

Note also that you cannot, portably at least, declare this overload in addition to the ones above:

If you do, you will numerous real overload resolution conflict errors particularly on aix.

Well, I'm glad you asked. Because template functions can be overloaded based on the types of parameters, you can create a family of functions with the same name but providing slightly different algorithms based on the types of the parameters actually passed. See Overloaded template functions above. And, yes, you can do this without doing anything special -- it is just helpful sometimes to be able to explicitly pass a parameter whose only purpose is to help establish which algorithm to use. For example, you might want a variety of copy() algorithms, each differing only the type of iterators it deals with, albeit with profoundly different algorithms based on those iterator types. You could have a variety of algorithms with exactly the same name and almost identical parameter lists, or you could have a single copy() interface that detects the types of iterators and then invokes a different algorithm, say copy_helper() with an additional parameter whose type makes it absolutely clear how one copy_helper() differs from another.

Passing a 'type' is really nothing more than passing a 0 -- its just that the compiler knows 'what kind of 0' you are talking about. The runtime performance implication is that of passing an extra parameter to the function.

When you pass a'type' as a parameter to a function, you are really doing nothing more than forcing the compiler to pick a specific overload from the family of functions with the same name. This is done extensively in the STL and can occassionally be useful as a general purpose tool to reduce unnecessary duplication of similar text (and the associated duplicate maintenance).

A good example of this from the STL is the distance() family of functions. This family of functions has the simple task of counting the number objects between two iterators.

The general form is like this:

As you can see the general algorithm is required to actually step through all the locations the iterator can point to. However, this is O(N) -- a good 'Big O', but not a great one. With some kinds of iterator, this is the best you can do. However, for iterators that are actually implemented as pointers, this is horrible. You should be able to do the calculation in O(1) time. In fact, for all random access iterators you should be able to calculate the distance between two iterators in constant time.

That is, the random access iterator form should look like this:

So the question is, how do you instruct the compiler as to which algorithm to use? The STL answer is to provide a family of related functions that perform the task in different ways and used overloaded template functions to implement the alternatives.

The general scheme works like this:

• There is a public interface that is documented.
• The public interface serves only to detect which specific interface needs to be actually used, and routes a call to that 'private' interface -- although it is not 'private' in the C++ sense.

In the distance() example, you could implement the public interface like this:

In this case, there are two iterator_helper implementations: one for plan vanilla iterators and one for random access iterators. There must also be a family of overloaded functions that help you detect which of the two helper algorithms should be used. Of course, this concept of 'iterator category' goes well beyond the distance() algorithm, so the STL provides a general purpose technique -- the iterator_category() family.

This functionality is documented in other places, but the general idea is that each of the kinds of iterators, is represented as a struct with no members. Something like:

• struct input_iterator_tag {};
• struct output_iterator_tag {};
• struct forward_iterator_tag {};
• struct bidirectional_iterator_tag {};
• struct random_access_iterator_tag {};

There are also, a collection of functions of which return an object of one of the above iterator category tags. Pointers are treated as random access iterators. The general format of these routines is like this:

Given that this family of routines exists, and there are two distance_helper functions with signatures like this:

     template<class Iter, class TagType>
     void distance_helper (Iter first, 
			   Iter last, 
			   Size_T size, 
                           TagType t)
     {
       // see the generic O(N) algorithm
     }

     template<class Iter>
     void distance_helper(Iter first, 
			  Iter last, 
                          Size_T size, 
			  random_access_iterator_tag)
     {
       // see the fast O(1) algorithm
     }

then, the optimal algorithm will be chosen:

• for pointers and random access iterators (like those in the vector class) the O(1) algorithm will be chosen.
• all other iterators will get the O(N) algorithm.

Specializing a template class is done in manner quite different from function overloading. Although, it is possible to specialize template functions in a manner similar to template class specialization. Explicit template function specialization lets you override the function body for a given type. Explicit class specialization lets you override a class' body for a given template parameter. Template specialization provides an alternative to virtual methods. Virtual function calls are neither terribly slow, nor terribly fast, but as Stroustrup points out, the iostream interface was designed so that it would not be necessary to have a virtual function call on very character read or written -- so it is an issue worth taking into account.

Here's how to use template specialization instead of virtual methods:

• Declare a normal template signature, but do not instantiate the bodies of class members or the body of the function if it is a global free function.
• Specialize the signature for all instances of interest, implementing function bodies and data members as needed. Note that you can add members to specialized template classes.

Here is a comparison between the above method and simply using virtual functions:

advantages

you don't have to pay the penalty for virtual methods, the implementations can be wildly different -- including different data types and members, different protection for functions, etc.

disadvantages

no inheritence relationship exists between classes

Use template class specialization instead of template class derivation to cut down on namespace pollution when you need conceptually related classes to have different numbers of members:

Use specialization to handle wierd stuff that should be associated with a class but which might be so bulky as to obscure readability of the original class:

Note that this mechanism helps make built in types more usable in templates because you can write code that assumes that a builtin class has a Helpers but you cannot assume that a builtin class has a nested method. For example, the following code won't compile: