The idea is that of "Unity builds" which I discovered from an answer by Christoph Heindl on Stack Overflow about how to speed up Visual Studio builds. Christoph refers to this blog entry; The Magic of Unity Builds which explains that due to disk accesses it's more efficient for a compiler to compile a single .cpp file that includes all of your other .cpp files and that this has a major effect on compilation time. Others suggest that this also results in better optimisation due to the fact that all of the code is visible to the optimiser at the same time, but this may not make that much difference to you if you have link time code generation and whole program optimisation turned on.

Anyway, I gave this a go for one of my libraries and it does indeed dramatically improve compile and link times when rebuilding the library. Of course that's the problem though, it always results in a complete rebuild. Because of this I don't see that it's especially suitable for day to day development where my "no precompiled headers" build configuration means that I only ever have to rebuild the code that has changed. However the Unity Build is faster than my complete rebuild with precompiled headers enabled so it might be useful for the integration builds on my build servers. Since my build servers also test that all of the normal build configurations work, and since I don't see me ever moving away from a standard build, I would only be able to use this technique for the integration builds for all compilers and platforms during the development process and I'd have to use my current method of compilation for the final test builds before release.

The problem with Unity Builds is that you end up with a single C++ "translation unit" rather than a series of translation units (one per source code file). Translation units are important in C++ compilation and there are some practices that rely on each file being a separate translation unit. In The Magic of Unity Builds, OJ refers to the problems that arise from merging translation units as being due to dodgy coding practices. I disagree here. The main problem that I've come across so far is that static variables and functions are, of course, local to the translation unit in which they're defined. With the single translation unit "unity build" approach you effectively lose the ability to declare static variables and functions. This is quite a big issue for me as I like to limit visibility as much as possible so functions that are used internally by a class and that do not need to be member functions are often implemented as file level static functions. Sure they could be implemented as class level, private, static functions but this exposes them to the header file and thus causes more code to require compiling if they're changed. Likewise file level static variables are sometimes useful. Rarely as variables but often as constants. The unity build approach means that you need to be careful with naming to avoid name clashes from your static functions. This may be a big enough issue for me that I wont use Unity Builds no matter how much they improve the speed of my integration test builds.

Another issue with Unity Builds is the additional build configurations required. To be of value to me during integration testing I would need to be able to build a Unity Build of each of my 4 standard build configurations (Debug, Unicode Debug, Release, Unicode Release). That means 8 more configurations to manage (4 for x86 and 4 for x64). Because of this, and because I expect that I'd want to strip the Unity Build from my released source code distribution, I expect that I'd place all of the Unity Builds in their own project file. So now each library would have two project files per compiler and an additional solution file that pulls them all together. These could be automatically generated from the standard project and solution files.

Finally there's the maintenance of the "Unity" file itself. Again this could be automatically generated, but it's likely to be more complex than simply creating a file that includes every .cpp file in the project. I'm sure that some of my libraries will have enough code that they will blow some internal compiler limits when compiled as a Unity Build. This means that I'll need some way of splitting the Unity file into several files to get around compiler limits - supporting 5 versions of Visual Studio is likely to make this more complex.

Because of all the skiing and partying and work out here I haven't been keeping up with many technical issues but this morning I checked bloglines and picked a couple of random feeds to catch up on. One of them was the Artima C++ Source feed which has recently published 5 articles by Scott Meyers. These articles are five lists of five of the "Best C++ ... ever", one on books, one on other publications, one on software, one on people and one on aha! moments. They're all worth reading.

std::list<std::pair<std::string,std::string> > tokens;
std::pair<std::string,std::string> token;

typedef std::pair<std::string, std::string> Token;
typedef std::list<Token> Tokens;
  
Tokens tokens;
Token token;

Even in the small code snippet above the use of a tiny abstraction, a name, makes the code easier to reason about. A Token is a pair of strings and Tokens is a list of Token data. The tiny abstraction allows us to be explicit about the relationship between the std::pair<std::string, std::string> that's used in the declaration of tokens and the corresponding use in the declaration of token. It's the same usage, the same abstraction; we call it a "Token". In real code, you'd no doubt manipulate this data a little more. Without the simple abstraction of the typedef the code required to iterate through that list of tokens would look something like this:

for(std::list<std::pair<std::string, std::string> >::const_iterator it = tokens.begin() ...

What should communicate quite clearly that you want to iterate over a series of tokens is, instead, full of implementation details that force you to fully understand, and reason about, what constitutes a token. The simplest abstraction, a name, moves the detail into "need to know" territory and reduces the amount of reasoning that you must do when working with the concept. Now, as I've said before, typedefs aren't perfect, but as a step towards abstraction they're valuable.

I have a rule of thumb that has served me quite well. As soon as you need to start worrying about the C++ parse problem that requires a space between the closing angle brackets of a template that is a template on a template (std::list<foo<bar> >) then you're missing a name for the inner template...

The token in the example above might be better off being defined as a specific kind of structure as it would allow us to convey more meaning and work at the level of the abstraction rather than at the level of the implementation. Using the token shown above we'd end up with code that operated in terms of the first and second elements of the std::pair template. Code like this:

DoThing(token.first);
  
DoSomethingElse(token.second);

The code above shows the standard names of the two elements of the pair. Whilst pair is useful it's often worth the time and effort to declare your own structure that's more suitable for your particular abstraction, even if it only has two elements. Once again the power of a name should not be underestimated. For the time taken to declare something like this:

struct Token 
{
   std::string name;
   std::string value;
};

You end up with code that reads better, communicates with the programmer and stays at the level of the abstraction rather than jarringly displaying implementation details. Although it's said that good programmers are lazy, failure to apply a little abstraction where it's required is the wrong kind of laziness. Amazingly, I've seen code that has built up some quite complex structures using nested pairs. Not surprisingly, the level of communication between code and programmer from a line that reads: DoStuff(first.second->first.first->second); is fairly low... The problem is that it's often not quite so obvious that the communication provided by a single pair is often equally as low.

As we've seen, naming data and groups of data can help build simple abstractions. Another way to create an abstraction is to move small pieces of code into simple functions. In my opinion, even if a function is only called from one place it's often worth having simply for the fact that the detail is hidden behind a name. Once again by naming something you can work at the level of the name, the concept, rather than at the level of the detail; you can drill down when you need to.

Working in terms of abstractions usually means thinking in terms of the problem that you're solving rather than in terms of the way that you're solving it. When you're doing this you'll often find that you don't tend to use 'raw' types that often. The abstraction that is a std::map lives in the realm of the solution whereas a "WidgetCollection" lives in the realm of the problem. What's more, and I've said this before, the abstraction of the std::map, or, indeed, most 'standard' abstractions, is too general to provide maximum value when working in the problem domain. A more precise, more focused abstraction allows you to work at a higher level. Just as "vehicle" is a valuable concept, the concept of a "bus" is more precise, and the concept of a greyhound bus or a routemaster even more so. If you are forced to communicate in terms of "vehicle" the whole time when referring to a Routemaster then you need to continually remind your audience that you should only enter through the opening at the rear and that it can't fly and can't travel on water... The more specialised the concept that you're working with the more precise your understanding of the operations that you can perform on it and the clearer it communicates its purpose.

Of course, as Joel Spolsky once pointed out in "The Law of Leaky Abstractions", abstractions tend to be "leaky" and you'll often find that you need to be able to work in terms of their component parts to be able to program effectively, but, and it's a very bit but, that doesn't remove the value of the abstraction and small, simple, abstractions can often be as valuable and powerful as larger ones.

In my opinion, being able to work at different levels of abstraction is one of the most important skills of a good programmer. Being able to build these abstractions from simpler abstractions is as important as is being able to drill down through them. In fact, I think it's more important. Often, programmers who can drill deeply through abstractions seem to focus on this at the expense of building their own abstractions. Whilst I agree that being able to cut through the names and concepts, breaking them apart into their component parts and drilling further and further until you end up at the assembler level is amazingly useful when you have a nasty bug to chase, or when an API doesn't function quite how you, or the documentation, expects. It's not always necessary to go all the way down to the "metal", it's just often useful if you can. Joel alludes to this in his "The Perils of Java Schools" piece; the more layers that you understand the more you can reason about your abstractions on multiple levels at the same time, switching effortlessly between the use of the concept to focus on the detail of the concepts that make up the abstraction that you're working with and those below it. However, if you focus on this at the expense of learning how to build your own abstractions then you're missing out and your code will only communicate at a very detailed and complicated level.

CWidget &CWidgets::Get(const std::string &name)

Although looking at much C++ code you might think it was.

The first, and simplest, use of const to improve code clarity is simply using it when defining variables that never change, constants. Say we have a function that calls a few other functions to obtain the data that it needs before doing its main work. If that data isn't changed by the function then it should be declared as const. This clearly communicates that the function doesn't change the data later on and it allows the compiler to protect you from accidental attempts to change the data. Seeing const means that you can mentally flag the value as a constant and that's one less thing to worry about. If a value would normally be set using an if statement but the result should be const then consider using the conditional operator (?:) instead.

Likewise, if parts of your object can never be changed after construction then they should be const so that a) they communicate the fact that they're immutable and b) so that they can't be changed by mistake. It's relatively simple to do, you burn in some of the business rules into the code and you prevent bugs. These parts of the object are not variable they're constant. If your object represents a trade and a trade has an ID that is assigned once and never ever changes then the trade ID should probably be constant within the trade object. The one down side is that you can't assign to the object as the left hand side object in the assignment can't be changed because it contains constant data; in practice I haven't found this to be a limiting factor in most cases, if it is then you can either use the "handle/body" idiom to allow you to maintain the constantness of the body whilst allowing assignment between handles or simply always work in terms of pointers or references to the object in question.

Finally you should use const in the interfaces to your classes so that you separate the interface into two, one that will modify the object and one that cannot. If a method is a query on the object and simply returns details of the object's state and doesn't change that state then the method should be declared const.

bool CLocationManager::Contains(
   LocationIndex location) const
{
   return m_callStacks.find(location) != m_callStacks.end();     
}

This serves three purposes; i) it communicates precisely what's going on, ii) it allows the compiler to prevent accidental mistakes within the body of the method, iii) it allows the method to be used on a constant instance of the object (which is extremely important if you're correctly declaring your constants to be const!).

The correct use of const is contagious. Once you get into the habit of using const to clearly declare your constants you'll find that you have to use const to correctly define your interfaces.

If you have a class that holds a reference to a collection that it never changes then this reference should be const. Once it is const the interface on the class must be correctly defined to provide both a query interface that is const and an "adjustment" interface that is not const. Part of the query inteface might look like this:

const CFunctionStack &CLocationManager::Get(
   LocationIndex location) const
{
   FunctionStacks::const_iterator it = m_functionStacks.find(location);

   if (it == m_functionStacks.end())
   {
      throw CException(_T("CLocationManager::Get()"), _T("Location: ") + ToString(location) + _T(" not found"));
   }

   return *(it->second);
}

Notice how this allows us to both limit what the function can do to the object and clearly communicate that limitation. The function can be used on a constant collection of locations as it cannot change that collection. Likewise it returns a constant reference to one of its contained objects. The caller has a "read-only" view of the collection. You can tell, quickly and accurately by looking at either the object in question or the start of the function if data will be changed.

As I've said before, being const correct means you need to think a little bit more when you write the code but you can trade that for thinking a little bit less when you read the code. Since code is read more times than it's written it's well worth being disciplined when you write code.

The thing about undefined behaviour is that, by definition, it can be anything. This makes it difficult to write unit tests for. Sure, it's possible to have the 'undefinedness' be something that integrates with your testing framework in debug builds but it's unlikely that you'd want it to do this in your release builds; especially if the purpose of the undefined behaviour is to improve performance by not checking things and trusting the caller. So, functions that include undefined behaviour in their contracts are hard to unit test under failure conditions that give rise to the undefined behaviour. You can write a test that exercises the code with a contractually correct usage pattern but you can't prove that the code fails when and how it should because you can't know what such a failure will do.

Obviously there may be other reasons that you either cannot or would prefer not to fail in a defined manner but they're generally few and far between (unless, perhaps, you're working on high performance generic container implementations). By all means think about providing an unchecked, undefined on failure, version of a function but don't bother implementing it or using it until your profiling has shown that the code that you think requires it actually does. With fine grained unit tests you should be able to determine the actual performance requirements reasonably quickly by unit testing the user of the code under the kind of situations that you expect performance to be critical. If you attempt to avoid undefined behaviour for as long as possible then you may often find that you don't actually really need it.

I know some people will say that there's nothing really to worry about because they can include an assert to validate that the caller is sticking to the contract. This is true but if the checking code remains in all builds of the code then the code need no longer exhibit undefined behaviour and if the checking code is not included in some builds then you may find yourself looking for heisenbugs since the code that runs in production may not be the same code that you can debug and test.

By definition, undefined behaviour is irrecoverable. Since there's no specification of what the behaviour is there's nothing you can do when it happens. If you're writing code that needs to be robust and needs to fail in a graceful and controlled manner than as soon as you step into undefined behaviour you cannot guarantee that the code is robust and you are incapable of failing gracefully under all situations.

Of course some people will claim that using functions which include undefined behaviour in their specifications is OK as long as the caller plays by the rules; this is true, to a point. The problem is that there's very little that you can do to prove that the caller is always going to play by the rules. Checks that compile out of release code may give you a warm fuzzy feeling when running tests in debug mode but they won't necessarily stop the software from failing in production. This is even more likely if the code in question uses multiple threads as thread scheduling is often the most affected by differences between debug and release builds.

What does all this mean in practice? You can usually avoid designing undefined behaviour if you always validate your input parameters and always document exactly how you will fail if they are invalid. This documentation may take the form of a unit test for the code in question, if it does then you can be sure that the documentation stays in sync with the code; the test fails if the documentation gets out of sync with reality.

I personally find that reasoning about references when examining code is less complex that reasoning about pointers. A reference can do less that a pointer, it's more precise because it can only refer to a valid object whereas a pointer can refer to a valid object or null. Each time you see a pointer you have to work out if it is likely to be valid from the context in which you see it and from where you obtained it from, when you see a reference you don't have to do that. Whilst reading, or working through, complex code that you're not that familiar with, pointers require that you remember more about a variable than references.

Of course, about now someone will pipe up with a comment that points out that you can subvert the C++ reference mechanism by deliberately creating a reference to a null pointer. That's true, but if you have programmers that are doing that then you have more fundamental problems that this tip might help you address.

As always, the devil is in the detail. What does it mean to remove unnecessary optionality in practice?

Assume we have a container that maps from string names to widgets. Widget objects are pretty large so we decide to store pointers to widgets in the container and have the container manage the lifetime of the widgets that it contains. This could be a simple stl::map but I tend to prefer a more precise interface so I would tend to write a wrapper class that exposes the interface that I actually need.

Suppose that the usage pattern for the collection of widgets is that they're loaded at program start up and the names are presented to the user so that they can select an appropriate widget to manipulate. What should the code that retrieves a widget from the collection look like?

Often you'll see code in the collection like this:

CWidget *CWidgets::Find(
   const std::string &name)
{
   CWidget *pWidget = 0;
   
   Widgets::iterator it = m_widgets.find(name);
   
   if (it != m_widgets.end())
   {
      pWidget = it->second;
   }
   
   return pWidget;
}

and code at the point of use like this:

CWidget *pWidget = m_widgets.Find(name);

assert(pWidget != 0);

DoThisWithWidget(pWidget);
DoThatWithWidget(pWidget);
// more code that manipulates the widget

One of the problems with this kind of code is that it doesn't clearly express what's going on. The code says the widgets collection may contain a widget with this name whereas the requirement is that the widgets collection always contains a widget with the supplied name. The collection is slightly more general purpose than it needs to be and because of this we inject a small amount of uncertainty into the code that uses it. Although the code following the assert may be protected from bugs that cause the collection not to contain the expected value the programmer still needs to reason in terms of a pointer, a potentially optional widget, rather than in terms of a reference to a widget that must exist. The slight addition in complexity is negligible at this point since you can easily see that the assert that states the pointer must always be valid, however, once we trace the code into DoThisWithWidget() or DoThatWithWidget(), or even as we move further away from the assertion code, things may, or may not, be more complex and harder to reason about.

My preferred solution to this accidental complexity is to remove the unnecessary optionality. Instead of using CWidgets::Find() as shown above we would use something like this:

CWidget &CWidgets::Get(
   const std::string &name)
{
   Widgets::iterator it = m_widgets.find(name);
   
   if (it == m_widgets.end())
   {
      throw CException("Widget: \"" + name + "\" not found");
   }
   
   return *(it->second);
}

This method on the widget collection will return a widget of the specified name if it exists and throw an exception if it doesn't. Obviously this is inappropriate if you need to find out if a widget exists in the collection, but it is appropriate if the widget must exist. What is done with the exception is up to the user of the widget collection, or, perhaps, the user of the user of the widget collection.

The code at point of use becomes something like this:

CWidget &widget = m_widgets.Get(name);

DoThisWithWidget(widget);
DoThatWithWidget(widget);
// more code that manipulates the widget

It's now quite clear that if the code ever returns from the call to Get() then you have a valid widget. Likewise, code following this point is clearly written with the intention of working with a widget that is always present. This allows our removal of optionality to "trickle down" to the functions that follow; DoThisWithWidget() and DoThatWithWidget() can now be written to take a reference and any assertions or checking for valid pointers inside them can be removed. Code such as this:

void DoThisWithWidget(
   CWidget *pWidget)
{
   assert(pWidget != 0);

   // do stuff with widget

void DoThisWithWidget(
   CWidget *pWidget)
{
   if (!pWidget)
   {
      // handle unexpected error, widget can't be null!
   }
   
   // do stuff with widget

need never exist. Instead we just have code that clearly communicates its expectations in a way that the compiler can confirm and that we, as programmers, can forget.

void DoThisWithWidget(
   CWidget &widget)
{
   // do stuff with widget

Often people will complain that they must use pointers rather than references for non-optional objects for some reason. Most of the time they're wrong ;) Sure, you may be passed a pointer that can never be null from an API that you're using but you don't need to pass this design pollution on to the rest of your code. Likewise you may use an API that requires a pointer but that doesn't mean you need to pass the object as a pointer within your own code.

Even when an object is optional you may still gain some clarity by removing the optionality. Of course if the object really is optional then you need to fabricate something to use when the optional object isn't present, for this you can often use the Null Object Pattern. This replaces an optional object which may be nothing with an object that will always be there but may do nothing. Using a Null Object often allows you to move switching based on the presence of the optional object and consolidate the "doing nothing" within the null object rather than spreading it across all the users of the object in question.