A basic understanding of C++ header files

Question

I have a theory question rather than an error report.

I'm a rookie C++ programmer, trying to promote that away

Using the VC++ VS2008 compiler

I am often finding myself wondering WHY I want to take some actions in header files.

For example look at this code block:

#include "DrawScene.h"
#include "Camera.h"
#include "Player.h"
#include "Grid.h"
#include "InputHandler.h"
#include "GameState.h"

class Controller
{
public:
private:
public:
 Controller();
 ~Controller(){}
 void Update();

private:
};

And the hooked up CPP file , controller.cpp along with it

#include "stdafx.h"
#include "glut.h"
#include "Controller.h"
#include <iostream>

Grid* grid_ptr = new Grid();
InputHandler* inputHandler_ptr = new InputHandler();
DrawScene* drawScene_ptr = new DrawScene();
GameState* gameState_ptr = new GameState();

Controller::Controller()
{

}

void Controller::Update()
{

}

What is a good way to decide which includes go where? So far I've been going with the " whatever works" method but I find it somewhat unprofessional.

Now even though you can say my code has X syntax errors and design flaws, please do, but the focal point I would appreciate that information remains on the use of .h VS .cpp files.

Why is there even such a design? And what are the pits and traps to always be treading lightly around when making any kind of OOP based C++ program?

What sparked this question for me btw was that I wanted to notify the reader of the header file there will be objects stored in the controller but assigning these uninitialized objects seemed impossible without making them static.

Note: I stem from C# --> C++ , might help to know. That's kind of my perspective on code at this point.

Thank you in advance for you efforts!

EDIT: 26/08/2010 18:16

So the build time is the essence of good includes. Is there more to be cautious about?

Answer 1

Only include headers in another header if absolutely necessary. If the header can go solely in the source file then that's the best place. You can use forward declarations of classes in the header if you are only using pointers and references to them. Your DrawScene, GameState, Grid and InputHandler classes looks like they might fall into this category.

Note that C++ as a language does not care about the distinction between headers and source files. That's just an extremely common system used by developers to maintain their code. The obvious advantage of using headers is to avoid code duplication and helps, to an extent, to enforce the one-definition-rule for classes, templates and inline functions.

Answer 2

This is my personal opinion rather than a consensus best practice, but what I recommend is: in a header file, only include those headers that are necessary to make the contents of the header file compile without syntax errors. And if you can use forward declarations rather than nested inclusions, do so.

The reason for this is, in C++ (unlike C#, iiuc) there's no export control. Everything you include from a header will be visible to the includers of the header, which could be a whole lot of junk that users of your interface should not see.

Answer 3

Header files contain declarations of functions, classes, and other objects, whereas cpp files are meant for implementing these previously declared objects.

Header files exist primarily for historical reasons. It's easier to build a C++ compiler if the definitions of all functions, classes, etc to be used by your code are given before you actually call them.

Usually you use cpp for your implemenation. Implementing functions in header files automatically inlines them, so unless these are very small and / or very frequently called, this is usually not what you want.

Answer 4

Generally speaking headers should reside in the cpp file. For standard library includes (and possibly 3rd library includes) you can stick them in headers. However headers defined specifically for your project should go in cpp files whenever possible.

The reason for this is compilation time and dependency issues. Any time you change a header file, the compiler will have to recompile every source file that includes it. When you include a header file in another header file, then the compiler has to recompile every cpp file that includes either header file.

This is why forward declaration and the PIMPL (Pointer to IMPLementation, or opaque pointer) pattern are popular. It allows you to shift at least some of the changes/implementation out of the header file. For example:

// header file:
class SomeType;

class AnotherType
{
private:
    SomeType *m_pimpl;
};

doesn't require you to include "sometype.h" whereas:

// header file
class AnotherType
{
private:
    SomeType m_impl;
};

does. EDIT: Actually, you don't need to include "sometype.h" in the "anothertype.h" if you ALWAYS include "sometype.h" before "anothertype.h" in EVERY cpp file that includes "anothertype.h".

Sometimes it can be difficult to move a header file to the cpp file. At that point you have a decision - is it better to go through the effort of abstracting the code so you can do so, or is it better to just add the include?

Answer 5

Avoid putting too many (read, any unnecessary) #includes in your .h file. Doing so can lead to long build times, as e.g. whenever you change Camera.h you will have changed Controller.h, so anything that includes Controller.h will need to be rebuilt. Even if it is only a comment that has changed.

Use forward declarations if you are only storing pointer members, then add the #includes to the cpp file.

Theoretically, .h files contain just the interface, and .cpp files, the implementation. However, since private members are arguably implementation, and not interface, this is not strictly true, hence the need for forward declarations in order to minimise unnecessary rebuilds.

It is possible, in C++, to include the whole implementation inline in the class definition, file, much as you might with Java, but this really breaks the .h/.cpp interface/implementation rule.