Recently, I encountered such approach of managing headers. Could not find much info on its problems on internet, so decided to ask here.
Imagine you have a program where you have main.c, and also other sources and headers like: person.c, person.h, settings.c, settings.h, maindialog.c, maindialog.h, othersource.c, othersource.h
sometimes settings.c might need person.c and main maindialog.c.
Sometimes some other source might need to include other source files.
Typically one would do inside settings.c:
//settings.c
#include "person.h"
#include "maindialog.h"
But, I encountered approach where one has global.h and inside it:
//global.h
//all headers we need
#include "person.h"
#include "maindialog.h"
#include "settings.h"
#include "otherdialog.h"
Now, from each other source file you only have to include "global.h"
and you are done, you get functionality from respective source files.
Does this approach with one global.h header has some real problems?
This is to please both pedantic purists and lazy minimalists. If all sub-headers are done the correct way there is no functional harm including them via global.h, only possible compile time increase.
Subheader would be somewhat like
#ifndef unique_token
#define unique_token
#pragma once
// the useful payload
#endif
If there are common headers that all the source files need, (like config.h) you can do so. (but use it like precompiled headers...)
But by including unnecessary headers, you actually increasing the compilation time. so if you have a really big project and for every source file you including all the headers, compilation time can be very long...
I suggest not include headers unless you must.
Even if you use type, but only for pointer or reference (especially in headers), prefer to use fwd declaration instead of include.
Related
I am currently abstracting OpenGL in C++ and I was just wondering if a certain practice I am doing is considered clean and efficient or the complete opposite. I have a header file which is included in close to almost every single header file for the abstraction called "pd.h" and in this file I include everything my program needs as such:
#pragma once
#include <GL/glew.h>
#include <GLFW/glfw3.h>
#include <glm/glm.hpp>
#include <glm/gtc/matrix_transform.hpp>
#include <glm/gtc/type_ptr.hpp>
#include <algorithm>
#include <iostream>
#include <fstream>
#include <string>
#include <sstream>
#include <vector>
Is this a very unclean and inefficient way for structuring my code? Because this is just how I've taught myself to do things and for some reason looking at it now it looks abit dodgy, and if it is not a good practice could someone explain why I shouldn't be doing this?
This is something that works, but it has two drawbacks, assuming you use a build system which compiles each .cpp file into its own .o file and only later links these into the executable.
Each time your pd.h file changes, all including files need to be recompiled. This means that your whole project has to be recompiled when you change this header. If you know that this file will not change often, then this is not a big drawback for a small project.
Build time is increased for each .cpp file because all those header files need to be processed, even though they are not needed. Compilers can precompile headers (check out for VS), though this is not part of the ISO C++ standard. Not including headers that are not used is an approach which is simpler to use and scales better.
The size of the executable will not change, nor the performance of the resulting application. Just the compilation time is increased.
So instead have the include only when you really need it. Is it sufficient to have it in the .cpp file? Do so. Only if it needs to be included in a header file, do so.
Sometimes you can get away with a forward declaration only. This is the case when the compiler does not need to know the size of the object because you are only defining a pointer to it in the current header.
When you use something, this is the order that I would try:
Include that header in the source file only
Use a forward declaration in the header file (might need to keep the include in the source file)
Include that header in the header file
There is a header iosfwd which has forward declarations for the iostream header, which can be helpful if you just provide overloads for operator<< for your class. These only take std::ostream & and therefore the compiler does not need to know the size.
I got a comprehension issue about precompiled headers, and the usage of the #include directive.
So I got my "stdafx.h" here and include there for example vector, iostream and string. The associated "stdafx.cpp" only includes the "stdafx.h", that's clear.
So if I design my own header file that uses for example "code" that's in vector or iostream, I have to include the header file because the compiler doesn't know the declarations at that time. So why are some posts here (include stdafx.h in header or source file?) saying, it's not good to include the "stdafx.h" in other header files even if this file includes the needed declarations of e.g. vectors? So basically it wouldn't matter to include directly a vector or the precompiled header file, both do the same thing.
I know of course, that I don't have to include a header file in another header file if the associated source file includes the needed header file, because the declarations are known at that time. Well, that only works if the header file is included somewhere.
So my question is: Should I avoid including the precompiled header file in any source file and why? And I am a bit confused, because I'm reading contradictory expressions on the web that I shouldn't include anything in header files anyway, or is it O.K. to include in header files?
So what's right now?
This will be a bit of a blanket statement with intent. The typical setup for PCH in a Visual Studio project follows this general design, and is worth reviewing. That said:
Design your header files as if there is no PCH master-header.
Never build include-order dependencies in your headers that you expect the including source files will fulfill prior to your headers.
The PCH master-header notwithstanding (I'll get to that in a moment), always include your custom headers before standard headers in your source files. This makes your custom header is more likely to be properly defined and not reliant on the including source file's previous inclusion of some standard header file.
Always set up appropriate include guards or pragmas to avoid multiple inclusion. They're critical for this to work correctly.
The PCH master-header is not to be included in your header files. When designing your headers, do so with the intent that everything needed (and only that which is needed) by the header to compile is included. If an including source file needs additional includes for its implementation, it can pull them in as needed after your header.
The following is an example of how I would setup a project that uses multiple standard headers in both the .h and .cpp files.
myobject.h
#ifndef MYAPP_MYOBJECT_H
#define MYAPP_MYOBJECT_H
// we're using std::map and std::string here, so..
#include <map>
#include <string>
class MyObject
{
// some code
private:
std::map<std::string, unsigned int> mymap;
};
#endif
Note the above header should compile in whatever .cpp it is included, with or without PCH being used. On to the source file...
myobject.cpp
// apart from myobject.h, we also need some other standard stuff...
#include "myobject.h"
#include <iostream>
#include <fstream>
#include <algorithm>
#include <numeric>
// code, etc...
Note myobject.h does not expect you to include something it relies on. It isn't using <iostream> or <algorithm>, etc. in the header; we're using it here.
That is a typical setup with no PCH. Now we add the PCH master
Adding the PCH Master Header
So how do we set up the PCH master-header to turbo-charge this thing? For the sake of this answer, I'm only dealing with pulling in standard headers and 3rd-party library headers that will not undergo change with the project development. You're not going to be editing <map> or <iostream> (and if you are, get your head examined). Anyway...
See this answer for how a PCH is typically configured in Visual Studio. It shows how one file (usually stdafx.cpp) is responsible for generating the PCH, the rest of your source files then use said-PCH by including stdafx.h.
Decide what goes in the PCH. As a general rule, that is how your PCH should be configured. Put non-volatile stuff in there, and leave the rest for the regular source includes. We're using a number of system headers, and those are going to be our choices for our PCH master.
Ensure each source file participating in the PCH turbo-mode is including the PCH master-header first, as described in the linked answer from (1).
So, first, the PCH master header:
stdafx.h
#ifndef MYAPP_STDAFX_H
#define MYAPP_STDAFX_H
// MS has other stuff here. keep what is needed
#include <algorithm>
#include <numeric>
#include <iostream>
#include <fstream>
#include <map>
#include <string>
#endif
Finally, the source files configured to use this then do this. The minimal change needed is:
UPDATED: myobject.cpp
#include "stdafx.h" // <=== only addition
#include "myobject.h"
#include <iostream>
#include <fstream>
#include <algorithm>
#include <numeric>
// code, etc...
Note I said minimal. In reality, none of those standard headers need appear in the .cpp anymore, as the PCH master is pulling them in. In other words, you can do this:
UPDATED: myobject.cpp
#include "stdafx.h"
#include "myobject.h"
// code, etc...
Whether you choose to or not is up to you. I prefer to keep them. Yes, it can lengthen the preprocessor phase for the source file as it pulls in the headers, runs into the include-guards, and throws everything away until the final #endif. If your platform supports #pragma once (and VS does) that becomes a near no-op.
But make no mistake: The most important part of all of this is the header myobject.h was not changed at all, and does not include, or know about, the PCH master header. It shouldn't have to, and should not be built so it has to.
Precompiled headers are a method to shorten the build time. The idea is that the compiler could "precompile" declarations and definitions in the header and not have to parse them again.
With the speed of todays computers, the precompilation is only significant for huge projects. These are projects with a minimum of over 50k lines of code. The definition of "signification" is usually tens of minutes to build.
There are many issues surrounding Microsoft's stdafx.h. In my experience, the effort and time spent with discovering and resolving the issues, makes this feature more of a hassle for smaller project sizes. I have my build set up so most of the time, I am compiling only a few files; the files that don't change are not compiled. Thus, I don't see any huge impact or benefit to the precompiled header.
When using the precompiled header feature, every .cpp file must begin by including the stdafx.h header. If it does not, a compiler error results. So there is no point in putting the include in some header file. That header file cannot be included unless the stdafx.h has already been included first.
Is there any valid reason for placing #include directives BEFORE the include guards in a header file like this:
#include "jsarray.h"
#include "jsanalyze.h"
#include "jscompartment.h"
#include "jsgcmark.h"
#include "jsinfer.h"
#include "jsprf.h"
#include "vm/GlobalObject.h"
#include "vm/Stack-inl.h"
#ifndef jsinferinlines_h___
#define jsinferinlines_h___
//main body mostly inline functions
#endif
Note, this example is a taken from a real life high profile open source project that should be developed by seasoned programmers - the Mozilla Spidermonkey open source Javascript engine used in Firefox 10 (the same header file also exists in the latest version).
In high profile projects, I expect there must be some valid reasons behind their design. What are the valid reasons to have #include before the include guard? Is it a pattern applicable to inline-function-only header files? Also note that this header file (jsinferinlines.h) is actually including itself through the last #include "vm/Stack-inl.h" (this header file includes a lot of other headers and one of them actually includes this jsinferinlines.h again) directive before the include guard, this makes even less sense to me.
Because you expect those headers to have include guards of their own, therefore it doesn't really make any difference.
Also note that this header file (jsinferinlines.h) is actually including itself through the last #include "vm/Stack-inl.h" (this header file includes a lot of other headers and one of them actually includes this jsinferinlines.h again) directive before the include guard, this makes even less sense to me.
It won't make any different because the workflow, when including that file, will be:
include all header up to "vm/Stack-inl.h"
include the "vm/Stack-inl.h" up to the last #include "jsinferinlines.h" (your file)
include the file jsinferinlines.h again (skipping all the previous includes, because include guards)
reach past #include "vm/Stack-inl.h"
finally process from #ifndef jsinferinlines_h___ on
But in general, mutual header recursion is bad and should be avoided at all costs.
There were lots of include cycles in SpiderMonkey headers back then, and placing the header guard at the top caused difficult to understand compile errors - I suspect that putting the header guard below the includes was just an incremental step toward sanitizing the includes.
I couldn't tell you the exact sequence of includes that caused it to make a difference, though.
Nowadays there shouldn't be any include cycles in SM headers, and their style is enforced through a python script written by Nicholas Nethercote. If you look at jsinferinlines.h today you'll see the header guard is at the top where it belongs.
I understand what a header guard is but I never saw how it is used in bigger projects. I am currently writing an OpenGL abstraction layer and I mostly need to include the same files.
So my first naive approach was to do something like this:
#ifndef GUARD_H
#define GUARD_H
#include <glm/glm.hpp>
#include <glm/gtc/matrix_transform.hpp>
#include <glm/gtc/type_ptr.hpp>
#include <GL/glfw3.h>
#include <glload/gl_core.h>
#include <glload/gll.h>
#endif // GUARD_H
So I can just do #include "guard.h". But I realized that this is not a really good solution because what if I want to add a simple include?
Yes I probably could write all my includes in this file but I am also not sure if this is a good idea either.
How would you recommend me to structure my header guards? Can you recommend me any resources?
Update 1: small example
test.h
#ifndef TEST_H
#define TEST_H
#include <glm/glm.hpp>
class test{
};
#endif
test1.h
#ifndef TEST1_H
#define TEST1_H
#include <glm/glm.hpp>
class test1{
};
#endif
now I included glm in my test class. but what if I want to do something like this.
#include "test.h"
#include "test1.h"
int main(){
//...
}
Don't I include #include <glm/glm.hpp> 2 times in main?
It's not a good idea to put all your includes in one files, except if you always include all those file.
You should only include the strict minimum of required headers in your own headers and include the rest directly in your .cpp source files.
Each of your headers should have a unique header guard without conflict with any other library, so take a very good care of the naming scheme.
You may also consider using the non-standard #pragma once directive, if you're not writing portable code.
You could take a look at this paper about the best practice for designing header files
To answer your edit :
No you don't include <glm/glm.hpp> twice, because it has itself a header guard. But you should include it only if you actually need glm.hpp inside your header, otherwise you should include it later. Note that you can often avoid the include by forward-declaring what you need, that could speed-up the compilation and avoid circular dependency, but that's another issue.
Simple. Header guards in every single header.
The way you've done it is unsafe : What if one day someone (not necessarily you, though even this is unsure) includes directly one of the headers you listed (though these are mostly external libs it seems, but it could evolve to include one of yours...), and this header doesn't have include guards ? Might as well exclude this possible issue ASAP !
To structure your headers, you should prefer to include what is strictly needed rather than everything in one global header.
Edit answer : No you won't include it twice. After the first include, every extra occurrence of the header guarded file will simply be ignored.
I had only just noticed my programs using the string class were compiling without including the <string> header. It turns out that <iostream> includes <ios_base> which in turn includes <string>.
Is this bad practice and should I explicitly include <string>? Even if it's just a case of clarity?
Is it safe to assume this applies to more than just the <string> header? Perhaps this is implementation specific and or does the standard state the <string> header be included via <ios_base> and <iostream>? Ensuring that any respected and widely used implementation will always include <string> providing the the call to <iostream> exists.
You should explicitly include whatever standard library headers you need.
It is not specified which standard library headers are included by other standard library headers, so such details will differ between compilers.
One case where you can rely on a header being included by another header is if a class in one header derives from a class in another. For example, <iostream> has to include <ios_base> because classes defined in <iostream> are derived from classes defined in <ios_base>.
A good practice is to always include the headers for the classes you'll be using in a given source file, regardless of whether you "know" they're included by already-included files.
If, while refactoring your code, you remove the necessity for one of the higher-level included files (iostream, for example), it could become quite painful to determine why your application no longer compiles.
If you add a proper header (with '#pragma once' or the proper #ifndef) more than once, it only adds a little more time to compiling (just to open, parse and through away the header file contents), but nothing too serious while it makes your files more easy to compile, should the circumstances change (i.e. move them to a different project, make a library out of them, e.t.c.)
If you are really concerned about compile time add the same #ifndef before including the header (though I don't recommend it)
i.e.
// header.h
#ifndef _HEADER_H
#define _HEADER_H
int blahblahblah(int);
#endif
// cppfile.cpp
#ifndef _HEADER_H
#include <header.h>
#endif