If you search the web for the best C++ source code, the Doom3 source code is mentioned many times, with comments like this one.
I spent a bit of time going through the Doom3 source code. It's probably the cleanest and nicest-looking code I've ever seen.
Doom 3 is a video game developed by id Software and published by Activision. The game was a commercial success for id Software, with more than 3.5 million copies sold.
On November 23, 2011, id Software maintained the tradition and released the source code of its previous engine. This source code was reviewed by many developers; here is, for example, some feedback from Fabien (original source):
Doom 3 BFG is written in C++, a language so vast that it can be used to generate great code but also abominations that will make your eyes bleed. Fortunately id Software settled for a C++ subset close to "C with Classes" which flows down the brain with little resistance:
- No exceptions.
- No References (use pointers).
- Minimal usage of templates.
- Const everywhere.
- Classes.
- Polymorphism.
- Inheritance.
Many C++ experts no longer recommend the "C with classes" approach. However, Doom3 was developed between 2000 and 2004, which could explain the lack of modern C++ mechanisms.
Let's go inside its source code using CppDepend and discover what makes it so special.
Doom3 is modularized using a few projects. Here's the list of its projects, along with some statistics about their types:
And here is the dependency graph showing the relationships between them:
Doom3 defines many global functions. However, most of the processing is implemented in classes.
The data model is defined using structs. To get a concrete idea of how structs are used in the source code, the metric view above shows them as blue rectangles.
In the Metric View, the code base is represented through a Treemap. Treemapping is a method for displaying tree-structured data by using nested rectangles. The tree structure used is the usual code hierarchy:
- Projects contain namespaces.
- Namespaces contain types.
- Types contain methods and fields.
As we can observe, many structs are defined — for example, more than 40% of DoomDLL types are structs. They are systematically used to define the data model. This practice is adopted by many projects, but this approach has a big drawback in the case of multithreaded applications: structs with public fields are not immutable.
There is one important argument in favor of using immutable objects: it dramatically simplifies concurrent programming. Think about it — why is writing proper multithreaded code such a hard task? Because it is hard to synchronize threads' access to resources (objects or other OS resources). Why is it hard to synchronize these accesses? Because it is hard to guarantee that there won't be race conditions between the multiple write and read accesses performed by multiple threads on multiple objects. What if there are no more write accesses? In other words, what if the state of the objects accessed by threads doesn't change? Then there is no more need for synchronization!
Let's search for classes that have at least one base class:
Almost 40% of structs and classes have a base class. In OOP, one of the main benefits of inheritance is polymorphism. The virtual methods defined in the source code are shown in blue:
More than 30% of methods are virtual. Few of them are pure virtual, and here is the list of all the abstract classes defined:
Only 52 abstract classes are defined, 35 of which are pure interfaces, i.e., all their virtual methods are pure.
Let's search for methods using RTTI.
Only very few methods use RTTI.
To summarize, only basic OOP concepts are used: no advanced design patterns, no overuse of interfaces or abstract classes, limited use of RTTI, and data is defined using structs.
Until now, nothing special differentiates this code from many others using "C with Classes" that are criticized by many C++ developers.
Here are some interesting choices made by its developers that help explain its success:
1. Provide a common base class with useful services
Many classes inherit from idClass:
idClass provides the following services:
- Instance creation.
- Type info management.
- Event management.
2. Make string manipulation easy
Strings are generally among the most widely used types in a project. Many operations involve strings, so we need functions to manipulate them.
Doom3 defines the idStr class, which contains almost all the useful methods needed to manipulate strings — no need to define your own methods, as is the case with many string classes provided by other frameworks.
3. The source code is highly decoupled from the GUI framework (MFC)
In many projects using MFC, the code is highly coupled with its types, and you can find MFC types everywhere in the code.
In Doom3, the code is highly decoupled from MFC; only GUI classes have a direct dependency on it, as shown by this CQLinq query:
This choice has a big impact on productivity. Indeed, only the GUI developers need to deal with the MFC framework; the other developers don't have to spend time dealing with MFC.
4. It provides a very good utility library (idlib)
In almost all projects, the most used types are utility classes, as shown by the result of this query:
As we can observe, the most used ones are utilities. If C++ developers don't use a good utility framework, they spend most of their development time fighting with the technical layer.
idlib provides useful classes with all the methods needed to handle strings, containers, and memory, which makes developers' work easier and allows them to focus more on the game logic.
5. The implementation is very easy to understand
Doom3 implements a hard-coded compiler, and as C++ developers know, developing parsers and compilers is not an easy task. However, the Doom3 implementation is very easy to understand, and its code is very clean.
Here's the dependency graph of the classes used by the compiler:
And here's a code snippet from the compiler source code:
We have already studied the source code of many parsers and compilers. But this is the first time we've encountered a compiler whose source code is so easy to understand — and it's the same for the whole Doom3 source code. It's magic. When we explore the Doom3 source code, we can't help but say: WOW, it's beautiful!
Summary
Even if the Doom3 design choices are very basic, but its designers make many decisions to let developers focus more on the game logic, and facilitate all the technical layer stuff. Which increase a lot the productivity.
However when using "C with Classes", you have to know exactly what you are doing. You have to be an expert, like the Doom3 developers. Beginners are not advised to take risks by ignoring modern C++ recommendations.