How to organize your code entities in header files?

Question

Possible Duplicate:
Best practices for use of C++ header files
C++ - What should go into an .h file?

I know it may be a trivial problem, but I am really confused about it.

• How should you organize your code entities in header files?

For example, put every class declaration in a header file. How about global entities? Do I need to put every declaration in a different file? Or put some related in a file? Or some other principles to determine it?

Example 1

// A common header file of "common.h"
#include <vector>
#include <memory>
#include <algorithm>
#include <string>
#include <cmath>

or just include them when they required.

Example 2

// A header file "report.h" to include functions to report some information
class string;
void Log(std::string& info); // show in a log window
void Message(std::string& info); // show in a message box
void Status(std::string& info); // show in a status bar

or split them to 3 files.

Answer 1

The first thing to remember is that a header is for use by other files; it should contain only the information needed by consumers of some service to use that service. A program in a single source file doesn't need a header (for the functions it defines; it will for the 'system' functions it uses, though). The header is used to ensure consistency between the provider of the service and the consumers of the service.

[Do you] put every class declaration in a header file?

No. Many classes, but certainly not every class.

If a class is only used by code in the source file, nothing outside the file needs to know about the class at all. The class should be specified in the source file, not in a header.

Even if a class is used in the interface, consider carefully whether the detailed declaration is needed, or whether it is sufficient to provide a forward declaration of the class.

How about global entities?

You should not have many 'global entities' other than functions. Avoid global variables as much as possible. If the global entity is going to be needed by other files, then it should be declared in an appropriate header, usually but not always the one that defines the class to which it belongs. If a 'global entity' is needed only in a single file, it should be defined in an appropriate namespace (often the anonymous namespace).

Do I need to put every declaration in a different file?

No. You group them together. Consider the Standard C++ Library. Many of the headers define more than one declaration. But each header defines a set of related declarations. You want to strike a balance between separating everything into different headers and having so many headers you can't find anything.

A first rule of thumb would be 'one header per source file that defines services'. It has to be used judiciously, though.

If several source files are needed to implement the complete set of services, then a single header may provide the external definitions for the complete set of services (and there will likely be a second, private header used only by the source files that implement the service, defining the details that they need to share between themselves, without sharing with consumers).

At the other extreme, sometimes a source file will implement several sets of services. It would be unusual if those services are not closely related — bad engineering. If they are related, then a single header can suffice. I suppose one could have two public headers for a single source file, but the situation would be extremely unusual.