What is the best header structure used in the library?

Question

As for the headers in the library, I see two options, and I'm not sure if this choice really matters. Suppose I created a library, called foobar . Please help me choose the most suitable option:

• Whether you include it in the very root of the library project, call foobar.h , which includes all the headers in the library, such as "src / some_namespace / SomeClass.h", etc. Then, from outside the library in the file I want to use, something to do with the foobar library is simply #include <foobar.h> .

• You don't have a basic include, and instead you only need to include the headers we need in the places where I use them, so I can have a whole bunch of inclusions in the source file. Since I use namespaces, sometimes up to 3, including the headers, seems a bit of a hassle.

I chose option 1 because of how easy it is to implement. OpenGL and many other libraries seem to do this, so this seemed reasonable. However, the C ++ standard library may require me to include multiple headers in any file, why didn't they have only one header file? If this is not my being and an idiot, but they are separate libraries ...

Update:

In addition to the answers, I think it makes sense to provide both options, right? I would be very annoyed if I wanted to use std :: string, but had to include a lot of header files; that would be stupid. On the other hand, I would be annoyed if I had to type a lot of #include lines when I wanted to use most of the library anyway.

Forward Headers:

Thanks to all that I advised about forward headers, it helped me make the jungle header less complicated! :)

Answer 1

stl, boost, and others that have many header files to include, they provide you with independent tools, and you can use them yourself.

So, if your library is a set of tools for decoupling, you should give the opportunity to include them as separate parts, as well as include the entire library as a single file.

Answer 2

Think a little about how your library will be used, and organize it that way. If someone is unlikely to use one small part without using all of this, structure it as one large. If a small part is independent and useful in its own right, make sure you can include enough for that part. If there is any logical grouping that makes sense, create include files for each group.

As with most programming questions, one size answer is not required.

Answer 3

All #included headers must be processed. This is not as bad as it could be, because modern compilers provide some ability to process them repeatedly (perhaps with something like #pragma once or ifndef protection). However, each #include header must be processed once for each translation unit, and this can add up quickly.

It is common practice that header files should # include only the header files they need and use the forward declarations as much as possible ( class foo; ). That way you won’t get the overhead.

If you want to # include everything and your brother, you can provide your own header file, which # includes everything. You do not need to explicitly write everything in each header and source file. This option is what you can provide, but if everything in std appeared as a single monolithic header, you would not have the option.

Answer 4

Each time you # include the header file, you make the compiler a rather difficult job. The fewer headers you #include, the less work it needs to do and the faster your compilation will be.

Answer 5

All included files should have their own meaning. And you should choose the header structure from the perspective of lib-users: how should users use my library? Which structure would be best for users?

examples:
if the library provides string algorithms, it would be better to make one header with all - string_algorithms.h;
if the library provides any one facade object, it would be better to use one header file (perhaps several other files with extensions or helpers),
if you provide a set of objects that will be used independently, create different header files (lib containers provide different containers);

Answer 6

Forward the announcement instead of including all of these header files at once, and then including how and when you need to.

Answer 7

However, if you define header files that you make available (one, several, or a combination of them) for a public library API, it is always useful to have at least one separate header for the private API. (There is no need to disclose prototypes of non-exported functions and classes or definitions that are for internal use only.)