How can I effectively use one file per class in C++?

Question

Even though I have a decent bit of professional experience with object oriented programming in Java and a basic familiarity with C, I've run into a bit of a mental block with C++ that I was hoping other developers could help me shine a light on.

In Java, almost every time I define a class I naturally create a new .java file. Of course there are the exceptions of internal and anonymous classes, but by and large a new class means a new file. With new classes come packages to organize them and so on, and as I've started dabbling in C++ I've taken that same approach of one .java file per class and extended it to one .hpp file and one .cpp file per class. However, it seems that there are a lot of problems with this approach. The one that's been on my mind lately is like this:

Say I have some kind of game where there is a class representing the game world and a class to represent the units. If the game world class has a method to get the unit at a location, that's all well and good. However, if I want to have a method for retrieving the containing world from the unit, the include directives won't resolve in the way that I'm used to building projects since each header includes the other. I know that there of course has to be a clean solution, and I want to know if some more experienced developers may have ideas on resources about C++ project organization, or on handling the specific construct I mentioned.

Answer 1

In C++ you have full flexibility how you want to organize your files. But you have to get accustomed to this freedom to make the good choices:

• A first practice is to have include guards in headers, in order to avoid that due to shared dependencies, the same header gets included multiple times.

• A second is discipline: make headers self-sufficient and always include in them all the required header dependencies. Make no assumptions about what the including code should have included else. Do not worry about mutual dependency: this is usually handled through forward declarations and separating declaration from implementation

• A third is to decide and use consistently what granularity you want for your headers: do you want a header per class (if you're used to it, why not continue) ? Or do you prefer a header for higher logical units (e.g. class and its auxiliaries) ?

• Then come the question of directories and namespaces (perhaps something that comes closes to the notion of java "packages" for the moment): do you keep files of different namespaces in different directories or not ? Note that this reflection may also be loosely related to the question of whether making a library subproject or not.

• Don't forget that you development environment could also influence the chosen directory structure (example or example).

For the future, it could be interesting to keep an eye on the concept of C++ modules. It's not yet standard, so you shouldn't build your current approach on it now. Yet it is interesting, as it intends to ease componentization of code using a java package like fashion, that would gradually get rid of headers. But it will still let you a big freedom for the file organisaton.

Answer 2

Say I have some kind of game where there is a class representing the game world and a class to represent the units. If the game world class has a method to get the unit at a location, that's all well and good.

I guess you mean something like this

// Gamworld.hpp
#pragma once

#include "Unit.hpp"

class Gameworld
{
     public:
       Unit GetUnit();
};

However, if I want to have a method for retrieving the containing world from the unit, the include directives won't resolve in the way that I'm used to building projects since each header includes the other.

No, you do not need to include the Gameworld.hpp in Unit.hpp if you use a forward declaration and use only pointers, references or shared pointers there:

// Unit.hpp
#pragma once

class Gameworld;

class Unit
{  
      Gameworld *world;

   public:
       Gameworld *GetWorld();
}

Only include Gameworld.hpp in Unit.cpp:

// Unit.cpp
#include "Gameworld.hpp"

Gameworld *Unit::GetWorld()
{
    return world;
}

I hope you get the basic idea. Though a bit outdated, I heavily recommend to get a copy of Lakos' book "Large Scale C++ Software Design", it will explain all the gory details and strategies about physical C++ file layout you need to know.

Answer 3

Your options for resolving circular dependencies are:

1. forward declaration

   Yes, this really is commonly used and isn't considered a hack.

   Note that only the public interfaces of your two interdependent types need the forward declaration: if the implementation is out-of-line, it's a separate translation unit, and there's no problem with each including the other's header.

   Note also that even if you put everything in a single header as Basile suggests, it's entirely normal to use forward-declaration even when the real declaration follows later in the same header.

2. type erasure

   Give the unit a pointer or reference to an abstract base class of the real game class, which itself has no dependency on the unit type. This does force the caller to cast, though.

   You could use void* instead of introducing an ABC, but that's even uglier.

The better option, though, is to break the dependency entirely if possible.

When do you actually have a unit object, but not the game context? Can't you just pass it in instead of making every unit object bigger to contain a reference to state the caller already had?

Answer 4

In C++11 (and other dialects of C++, and in C) you can have several translation units for a given program. So your program could be made of foo.cc, bar.cc, gee.cc C++ source files compiled separately and linked together. If using GCC (e.g. on Linux), you would compile your program with e.g.

 g++ -Wall -g -c foo.cc
 g++ -Wall -g -c bar.cc
 g++ -Wall -g -c gee.cc

^{Above: -Wall asks for all warnings, -g asks for debug information, -c asks only for compilation without linking.}

(so foo.cc gets compiled into the foo.o object file, bar.cc into bar.o, and so on) and later link it (into a progbin executable) with

 g++ -g foo.o bar.o gee.o -o progbin

In practice you won't type the commands each time, but you would use a builder like make to drive and run the above commands (see this and that examples of Makefile-s). The commands above are for a simple case, read the documentation about Invoking GCC for more (and order of arguments to g++ matters a lot!). You often want to add -Idir options for compiling with some include directory dir, and -Ldir & -lname options for linking (add a library directory dir, and use a given library name).

You want to avoid writing (and copy/pasting) the same declarations multiple times in each source file. You may (and sometimes need to) have forward declarations and opaque pointer types (you want to use smart pointers extensively), read about the PIMPL idiom. So you'll have a common myprog.h header file (or several header files) which would be #include-d by every source file foo.cc, bar.cc etc....).

There is no obligation regarding header and source files. In particular (contrarily to Java) you can (and often want) to have several declarations in a header file, and several class and function definitions (& implementation) in a source file.

So for a small (less than 50KLOC) project, I would recommend having one single common header file (with all the declarations) which might be precompiled and a few source files. But that is mostly a matter of opinion: I like having a single header file (of a few thousand lines) and few source files (of a few thousand lines) but some people like having many small header files and small source files (that makes the compilation time slower).

^{Once you have debugged your program (with the help of gdb and valgrind, perhaps using some instrumentation options by compiling and linking with -fsanitize=address or -fsanitize=undefined or other -fsanitize= options), you might want to profile or benchmark it. For profiling, compile with -pg after -g and use gprof and/or oprofile. For benchmarking, you want to ask the compiler to optimize with -O2 .}

In practice, look into existing free software code (e.g. on github) for concrete examples.