Related
I've seen fairly consistent advice that an implementation file (.cc / .cpp) should include its corresponding class definition file first, before including other header files. But when the topic shifts to header files themselves, and the order of includes they contain, the advice seems to vary.
Google coding standards suggest:
dir2/foo2.h (preferred location — see details below).
C system files.
C++ system files.
Other libraries' .h files.
Your project's .h files.
It is unclear what the difference is between entry 1 and 5 above, and why one or the other location would be chosen. That said, another online guide suggests this order (found in the "Class Layout" section of that doc):
system includes
project includes
local includes
Once again there is an ambiguity, this time between items 2 and 3. What is the distinction? Do those represent inter-project and intra-project includes?
But more to the point, it looks as if both proposed coding standards are suggesting "your" header files are included last. Such advice, being backwards from what is recommended for include-ordering in implementation files, is not intuitive. Would it not make sense to have "your" header files consistently listed first - ahead of system and 3rd party headers?
The order you list your includes shouldn't matter from a technical point of view. If you designed it right, you should be able to put them in any order you want and it will still work. For example, if your foo.h needs <string>, it should be included inside your foo.h so you don't have to remember that dependency everywhere you use foo.
That being said, if you do have order dependencies, most of the time putting your definition file last will fix it. That's because foo.h depends on <string>, but not the other way around.
You might think that makes a good case for putting your definition file last, but it's actually quite the opposite. If your coding standards require the definition first, your compiler is more likely to catch incorrect order dependencies when they are first written.
I'm not aware of any verbatim standard but as a general rule of thumb include as little headers as possible especially within other header files to reduce compile times, conflicts, and dependencies. I'm a fan of using forward declaration of classes in header files and only including the header and definition on the .cpp side whenever I can afford to do so.
That said my personal preference is below:
For Headers:
C++ headers
3rd party headers
other project headers
this project's headers
For Source:
precompiled header file
this source file's header
C++ headers
3rd party headers
other project headers
this project's headers
Pointers or suggestions are usually to avoid conflicts and circular references, otherwise it's all personal preference or whatever policy you prefer adhere to for collaborative projects.
Regarding Google's style:
There is no ambiguity, at all.
The first header included should be the header related to this source file, thus in position 1. This way you make sure that it includes anything it needs and that there is no "hidden" dependency: if there is, it'll be exposed right away and prevent compilation.
The other headers are ordered from those you are the least likely to be able to change if an issue occurs to those you are the more likely to. An issue could be either an identifier clash, a macro leaking, etc...
By definition the C and C++ systems headers are very rarely altered, simply because there's so many people using them, thus they come second.
3rd party code can be changed, but it's generally cumbersome and takes time, thus they come third.
The "project includes" refer to project-wide includes, generally home-brawn libraries (middle-ware) that are used by several projects. They can be changed, but this would impact the other projects as well, they come fourth.
And finally the "local includes", that is those files who are specific to this project and can be changed without affecting anyone else. In case of issue, those are prime candidates, they come last.
Note that you can in fact have many more layers (especially in a software shop), the key idea is to order the dependencies starting from the bottom layer (system libs) to the top layer.
Within a given layer, I tend to organize them by alphabetical order, because it's easier to check them.
For Headers:
this project's headers
other project headers
3rd party headers
C++ headers
For Source:
this source file's header
this project's headers
other project headers
3rd party headers
C++ headers
This orders minimize the chance to MISS some required header inside .hpp file. Also it minimize INTERSECTIONS of 3rd party headers etc. And all hpp modules compiles with minimum required dependensis.
for example:
->test.hpp
// missing #include <string> header
void test(std::string& s);
->test.cpp
#include <string>
#include "test.hpp"
// we hide bug with missing required header
->test2.cpp
#include "test.hpp"
#include <string>
// compilation error with missing header
Concerning headers in a library, I see two options, and I'm not sure if the choice really matters. Say I created a library, lets call it foobar. Please help me choose the most appropriate option:
Have one include in the very root of the library project, lets call it foobar.h, which includes all of the headers in the library, such as "src/some_namespace/SomeClass.h" and so on. Then from outside the library, in the file that I want to use anything to do with the foobar library, just #include <foobar.h>.
Don't have a main include, and instead include only the headers we need in the places that I am to use them, so I may have a whole bunch of includes in a source file. Since I'm using namespaces sometimes as deep as 3, including the headers seems like a bit of a chore.
I've opted for option 1 because of how easy it is to implement. OpenGL and many other libraries seem to do this, so it seemed sensible. However, the standard C++ library can require me to include several headers in any given file, why didn't they just have one header file? Unless it's me being and idiot, and they're separate libraries...
Update:
Further to answers, I think it makes sense to provide both options, correct? I'd be pretty annoyed if I wanted to use a std::string but had to include a mass of header files; that would be silly. On the other hand, I'd be irritated if I had to type a mass of #include lines when I wanted to use most of a library anyway.
Forward headers:
Thanks to all that advised me of forward headers, this has helped me make the header jungle less complicated! :)
stl, boost and others who have a lot of header files to include they provide you with independent tools and you can use them independently.
So if you library is a set of uncoupling tools you have to give a choice to include them as separate parts as well as to include the whole library as the one file.
Think a bit about how your libary will be used, and organize it that way. If someone is unlikely to use one small part without using the whole thing, structure it as one big include. If a small part is independent and useful on its own, make sure you can include just enough for that part. If there's some logical grouping that makes sense, create include files for each group.
As with most programming questions, there's no one-size-fits-all answer.
All #included headers have to be processed. This isn't as bad as it could be, since modern compilers provide some sort of option for not processing them repeatedly (perhaps with something like #pragma once, or an ifndef guard). Still, every #included header has to be processed once for each translation unit, and that can add up fast.
The usual practice is for header files to #include only those header files they need, and to use forward declarations (class foo;) as much as possible. That way, you don't get the overhead.
If you want to #include everything and its brother, you can provide your own header file that #includes everything. You don't have to explicitly write everything out in every header and source file. That option is something you can provide, but if everything in std came as one monolithic header, you wouldn't have an option.
Every time you #include a header file you make the compiler do some pretty hard work. The fewer headers you #include, the less work it has to do and the faster your compilations will be.
All include files should have own sense. And you should choose header structure from lib-users positions: how users should use my library? what structure will best for users?
examples:
if you library provide string algorithms - it will be better make one header with all - string_algorithms.h;
if you library provide some one facade object - it will be better to use one header file ( maybe few other files with extensions or helpers );
if you provide complex of objects which will be used independently make different header files (containers lib provide different containers);
Forward declare instead of including all those header files at once, then include as and when you need.
However you decide on the header file(s) that you make available (one, several or some combination thereof) for the library's public API, it's always a good idea to have at least one separate header for the private API. (No need to expose the prototypes of the non-exported functions and classes or the definitions that are only intended to be used internally.)
One of the things I'm having a hard time understanding is how the compiler works. I'm having a lot of difficulties with it, but in particular I keep getting headers and libraries mixed up. If somebody could clear things up a bit, that'd be great.
Think of both like this (Disclaimer: this is a really high-level analogy ;) ..
The header is a phone number you can call, while...
...the library is the actual person you can reach there!
It's the fundamental difference between "interface" and "implementation"; the interface (header) tells you how to call some functionality (without knowing how it works), while the implementation (library) is the actual functionality.
Note: The concept is so fundamental, because it allows you flexibility: you can have the same header for different libraries (i.e. the functionality is exactly called in the same way), and each library may implement the functionality in a different way. By keeping the same interface, you can replace the libraries without changing your code.
And: you can change the implementation of the library without breaking the calling code!
A header file is generally used to define an interface or set of interfaces within an application. Think of a header file as something which shows the external functionality of a program while omitting the technical implementation details.
For example, if you were optimising a program, you would most likely modify the source (.cpp) file to improve the algorithm, but the header file wouldn't change, because external clients still call the methods using the same set of parameters and return values.
In an object-oriented language like C++, a header file generally includes the following:
Class description and inheritance hierarchy
Class data members and types
Class methods
While there is nothing stopping code from being implemented in a header file, this is generally not favoured as it can introduce extra coupling and dependencies in the code.
In some cases (e.g. templated classes) the implementation must be defined in the header file for technical reasons.
A library is a collection of code which you want to make available to a program or group of programs. It includes the implementation of a particular interface or set of interfaces.
Code is defined in a library to prevent code duplication and encourage re-use. A library can be statically-linked (.lib) or dynamically-linked (.dll):
A statically-linked library defines a set of export symbols (which can be thought of as method definitions) which are then linked into the final executable (.exe) during the linking stage of the build process. It has the advantage of faster execution time (as the library doesn't need to be dynamically loaded), at the expense of a larger binary (because the methods are essentially replicated in the executable file).
A dynamically-linked library is linked during the execution of a program, rather than the linking of a program. It is useful when multiple programs need to re-use the same methods, and is used extensively in technologies such as COM.
One thing that may be confusing you is that the word library can have several meanings in C++. One meaning has been well-discussed here:
A linkable set of functions in a binary file. These can be statically linked or dynamically linked.
But there is another type of library: so-called header-only libraries (including parts of STL, TR1 and Boost). These do not exist in a separate binary form so the word library does not refer to a particular binary file but rather to a set of included header files.
Hope this helps.
Header only contains the declaration, whereas libraries also contains the implementaion.
A library is code, compiled into a set of object files. The object files contain the compiled machine code and the data declarations used by the code.
A header file defines the interface to a library: it tells you how to use the library correctly. In C/C++, a header file gives you a list of function names and how to call those functions: the number and types of parameters they take, the return type, the calling convention, etc. Header files have a lot of other stuff in them, too, but in the end, what it boils down is a set of rules for calling library code.
If Library in programming languages is a general library , then many books present in the library can be compared with functions/methods in languages . And also header files can be compared with the row number of the book
Suppose there is a book in some library in Hyderabad and in that library , that book is present in row Number 24 ...
The same way the address of the library is given by using the namespace std (for standard library) and row No is given by header file where all the books(methods in this case) of same time(all methods related to input/output streams) are put up
Header is typically used to contain the prototypes. Headers expand at pre-processing time so that at compile time, the code may have access to relevant function declarations/ prototypes.
Library is the actual software that contains the definitions of the function prototypes (present in the header). Library is used at link time. The definitions (present in library) are resolved at link time.
A header file describes how to call the functionality, a library contains the compiled code that implements this functionality.
HEADER FILE is that in which declaration of a function is written.By using header file we can access a particular function
while
LIBRARY FILE is that in which definition of a particular function is written.
MATH.H is a HEADER FILE while MATH.LIB is library file.
Working of HEADER File and LIBRARY in a Program.
A header file contains the links to libraries(libraries contain standard functions and methods), a compiler recognizes the standard functions used in the source code via a preprocessor, that resolves all the directives(directives are the lines in program preceded by # sign that include ) before the actual compilation of the program.
Thanks for reading!
I think library as a package of code which is reused many times and and that code is precompiled , hence it is available in standard form so that we do not have to write that code for every program that we develop .
And header file contain the reference to that code in simple way the functions we use in our program like "cin" and "cout" are fully defined in a standard library ,and header files like iostream header file contains the reference to that code.
So when we compile our code it we just get the precompiled for cin and cout, and we do not have to write the code for cin and cout for every time we use it.
Or In a more simple way we can say that a library contain codes for all the functions and a header file is way to reach that code.
A library is a collection of similar objects for occasional use . It usually contains programmes in object or source code form, templates, etc.
A header file is the location (interface) of the library
To paraphrase a classical joke, the difference is that the library has a header file while the header file doesn't have a library.
Libraries are like dead mummies,wrapped in white long threads. They are dead. Only way to release them is through header files. Header files contain ways to bring them to life and they can be brought to life many times(code reuse).
You can consider this example to understand- Math.h is a header file which includes the prototype for function calls like sqrt(), pow() etc, whereas libm.lib, libmmd.lib, libmmd.dll are some of the math libraries. In simple terms a header file is like a visiting card and libraries are like a real person, so we use visiting card(Header file) to reach to the actual person(Library).
Code from libraries will only be stored as needed for a header file. The whole header file will be stored, which saves processor storage area.
What are the C++ coding and file organization guidelines you suggest for people who have to deal with lots of interdependent classes spread over several source and header files?
I have this situation in my project and solving class definition related errors crossing over several header files has become quite a headache.
Some general guidelines:
Pair up your interfaces with implementations. If you have foo.cxx, everything defined in there had better be declared in foo.h.
Ensure that every header file #includes all other necessary headers or forward-declarations necessary for independent compilation.
Resist the temptation to create an "everything" header. They're always trouble down the road.
Put a set of related (and interdependent) functionality into a single file. Java and other environments encourage one-class-per-file. With C++, you often want one set of classes per file. It depends on the structure of your code.
Prefer forward declaration over #includes whenever possible. This allows you to break the cyclic header dependencies. Essentially, for cyclical dependencies across separate files, you want a file-dependency graph that looks something like this:
A.cxx requires A.h and B.h
B.cxx requires A.h and B.h
A.h requires B.h
B.h is independent (and forward-declares classes defined in A.h)
If your code is intended to be a library consumed by other developers, there are some additional steps that are important to take:
If necessary, use the concept of "private headers". That is, header files that are required by several source files, but never required by the public interface. This could be a file with common inline functions, macros, or internal constants.
Separate your public interface from your private implementation at the filesystem level. I tend to use include/ and src/ subdirectories in my C or C++ projects, where include/ has all of my public headers, and src/ has all of my sources. and private headers.
I'd recommend finding a copy of John Lakos' book Large-Scale C++ Software Design. It's a pretty hefty book, but if you just skim through some of his discussions on physical architecture, you'll learn a lot.
Check out the C and C++ coding standards at the NASA Goddard Space Flight Center. The one rule that I specially noted in the C standard and have adopted in my own code is the one that enforces the 'standalone' nature of header files. In the implementation file xxx.cpp for the header xxx.h, ensure that xxx.h is the first header included. If the header is not self-contained at any time, then compilation will fail. It is a beautifully simple and effective rule.
The only time it fails you is if you port between machines, and the xxx.h header includes, say, <pqr.h>, but <pqr.h> requires facilities that happen to be made available by a header <abc.h> on the original platform (so <pqr.h> includes <abc.h>), but the facilities are not made available by <abc.h> on the other platform (they are in def.h instead, but <pqr.h> does not include <def.h>). This isn't a fault of the rule, and the problem is more easily diagnosed and fixed if you follow the rule.
Check the header file section in Google style guide
Tom's answer is an excellent one!
Only thing I'd add is to never have "using declarations" in header files. They should only be allowed in implementation files, e.g. foo.cpp.
The logic for this is well described in the excellent book "Accelerated C++" (Amazon link - sanitised for script kiddie link nazis)
One more point in addition to the others here:
Don't include any private definitions
in an include file. E.g. any
definition that is only used in
xxx.cpp should be in xxx.cpp, not
xxx.h.
Seems obvious, but I see it
frequently.
I'd like to add one very good practice (both in C and C++) which is often forsaken :
foo.c
#include "foo.h" // always the first directive
Any other needed headers should follow, then code. The point is that you almost always need that header for this compilation unit anyway and including it as a first directive warrants the header remains self-sufficient (if it is not, there will be errors). This is especially true for public headers.
If at any point you need to put something before this header inclusion (except comments of course), then it is likely you're doing something wrong. Unless you really know what you are doing... which leads to another more crucial rule => comment your hacks !
When providing a library to others, documentation of e.g. class member functions can be included in the header files which contain the declarations. If properly formatted, this documentation can also be interpreted and displayed by IDEs.
Using C++ modules, how can I pass on information about the functionality in the module without falling back to external documentation, e.g. Doxygen? I assume comments do not make it as such into the compiled interface file?
You are right, this question is actually pointless. I thought that - unless provided with the complete source code - libraries would be provided completely in binary format when using modules. Although the idea of deploying just one library file without additional files has its charme.