How to use #include in big projects? - c++

Should I #include everything I need in every header/cpp file? I am working on a 2d game engine atm (for practice mostly) and in reviewing my code I realise that I repeat string and vector in almost every file. Is this an issue and how do I deal with it?
I've always had the opinion that every class or module you write should stand on it's own two legs, so to speak. I really enjoy generic programming (I'm including my own script language in the engine, with my own drafted script engine) but I also realise it could cause a lot of overhead and confusion.

I would stick to including <string> and <vector> only where necessary.
As for making sure individual header files stand on their own, I like how the Google C++ Style Guide deals with include order. Basically, always list the corresponding foo.hpp include before all other includes in foo.cpp. That way, we know that foo.hpp won't expect something to be included before it and fail if it isn't there.

It's not an issue. You should include, in every file, the absolute minimum dependencies- no more, but no less.

Related

C++ - Are there benefits of using #include <ClassName> instead of #include <classname.h>?

I know that the standard libraries use includes with .h for the old C libraries and includes without .h for the up to date libraries. But what is the better practice for one's own classes?
Where I work we always had an include folder with two files per class: classname.h and ClassName. ClassName includes the classname.h and classname.h includes the real class header. To include a class you then use
#include <ClassName>
That's the way Qt does it, and I'm pretty sure Qt is the reason they started doing it in my company. But are there any benefits of that?
The drawbacks are pretty obvious, I think:
One more file to create for a new class (we do it with a bash script, but still)
One more file per class to manage
When renaming a file/class via an IDE you usually have to adapt the ClassName file by hand (even Qt Creator can't do that)
I have never seen this style anywhere other than the std library and Qt
Do you use this style? If so, why? What are arguments for it? Are there more arguments against it?
First, I'm going to make up a term and call it "Class-Specific Include File" or "CSIF". These files do not end in .h, even though they are used like a header, thus the "include file" part. Since I'm going to keep referring to the thing, I might as well give it an acronym, too.
How this is implemented in Qt
Qt has a "header" file with no extension for each defined Qt class or struct, known as CSIF for this answer. CSIFs go right into the \include path with normal header files, but they all do the same thing if you open one up. Let's start with with include files in QtWidgets, particularly the ones related to QStyleOption:
\include
...
QStyleOption
qstyleoption.h
QStyleOptionButton
QStyleOptionComboBox
...
If you open up one of those QStyleOption-related CSIFs, all contain one line of code:
#include "qstyleoption.h"
And in qstyleoption.h:
#include "../../src/widgets/styles/qstyleoption.h"
All that the CSIF does is #include the correct header from the source tree for the class it is named after. It creates a level of abstraction between the actual definition of the class and #include statement needed to use it. As a result, this code:
//In some .cpp file somewhere
#include <QStyleOptionButton>
#include <QStyleOptionComboBox>
includes the same header file (protected by guards, of course), but the developer using Qt doesn't need to know that. All the developer cares about is that s/he's using a class, and s/he wants to be certain that the class is available. I don't know if this was the original logic, but that's the effect it has.
Answers to your specific questions
1. Do you use this style? If so, why?
Yes, but only because the project I'm working on emulates the Qt library style, so that Qt developers can use it comfortably alongside Qt. Otherwise, [insert profuse swearing].
2. What are arguments for it?
The only good argument I know of for it is above, in how Qt uses it to abstract-away classes and the location of their definitions. As a user of Qt, ensuring I have the proper header files included is a breeze. If I use class QFoo, I include: <QFoo>. Simple.
3. Are there more arguments against it?
There are plenty of arguments against it, as you noted in your question.
It makes refactoring many times harder.
It's only truly useful if you're developing a library.
It's only worth your time if your library has an API stability guarantee and is reasonably mature, because it makes refactoring many times harder.
It means every class your library exports must have a CSIF, and missing one is easy to do.
I'm sure others can come up with more examples of CSIF making life difficult. In all, one must weigh the balance of the increased rigidity it creates in your library and the benefits to the end-developer before making a decision.
As for how your workplace uses it... I'm shrugging. Someone copied the Qt style without understanding why, perhaps?

C++ headers difference

Very new to programming and have some questions about headers.
In the book it uses:
#include "std_lib_facilities.h"
My teacher always uses:
#include <iostream>
using namespace std;
Any reason why we would use one over another? One work better than the other? Any help would be appreciated. 😊
The headers included in a file change from file to file based on the needs of the file. What Stroustrup uses works in the context of his source examples. What your teacher uses matches the teacher's needs.
What you use will depend on your needs and the needs of the program.
Each file should contain all of the headers required to be complete and no more. If you use std::string in the file, #include <string>. If you use std::set, #include <set>.
It may appear to be unnecessary to include some header files because another include includes them. For example since iostream already includes string, why bother including both iostream and string? Practically it may not matter, string was included, but it is now a maintenance issue. Not all implementations of a given header will have the same includes. You will find yourself in interesting cases where the code compiles in one compiler, or version of the compiler, and not another because an include dependency changed in a header possibly two or three includes down the chain.
It is best to head that off for you and everyone who may follow in maintaining your code.
If you are not concerned about maintenance, look up the y2k bug. That was a problem because software written to meet the needs and constraints of the 1960's and 1970's was still being used 40 years later in a world with different needs and vastly different constraints. You'd be surprised how much code outlives the expected lifetime.
While it's nice to have certain employment for the rest of your life, it sucks to blow a weekend of your Hawai'i vacation because the modification to your that could have been done by a co-op turned into a nightmare because GCC 7.12 is just plain different from the GCC 5.2 under which you originally wrote the program.
You will also find that as long chains of files get included, a poorly constructed header can inject ordering dependencies on headers. Program X works fine if header Y is included before header Z. This is because Z needs stuff included by Y that Z did not declare. Don't be the person to write Z.
However, don't include everything. The more you include, the longer it takes to compile and the more exposure you have to unforeseen combinations reacting badly. Like it or not, someone always writes header Z, and you don't want the kick to the schedule debugging Z causes if you don't to include Z.
Why does it take longer to compile? Think of each include as a command for the compiler (preprocessor, really) to paste the included file into the including file. The compiler then compiles the combined file. Every include needs to be loaded from disk (slow), possibly security scanned (often awesomely slow), and merged into the file to be compiled (faster than you might expect). All of the included file's includes are pasted in, and before you know it, you have one huge mother of a file to be parsed by the compiler. If a huge portion of that huge file is not required, that's wasted effort.
Avoid like the plague structures that require header Y including header Z and header Z including Y. An include guard, more on that later, will protect the obvious recursion problem (Y includes Z includes Y includes Z includes...), but also ensures that you cannot include either Y or Z in time to satisfy Z or Y.
Some common headers, string is a favourite, are included over and over again. You don't want to keep re including the header and its dependencies, but you also want to make sure it has been included if it hasn't. To solve this problem you surround your headers with a Header guard. This looks like:
#ifndef UNIQUE_NAME
#define UNIQUE_NAME
// header contents goes here
#endif
If UNIQUE_NAME has not been defined, define it and replicate the header contents in the file to be compiled. This has a couple problems. If UNIQUE_NAME is not unique, you're going to have some really freaky error "not found" messages because the first header guard will block the include of the next.
The uniqueness problem is solved with #pragma once, but #pragma once has a few problems of it's own. It's not standard C++ so it is not implemented in all compilers. #pragma instructions are silently ignored (unless compiler warnings are turned way up and sometimes not even then) if the pragma is not supported by the compiler. Utter chaos ensues as headers are repeatedly included and you'll have warning. #pragma once can also be fooled by complicated directory structures including network maps and links.
So...
Stroustrup is using #include "std_lib_facilities.h" because it includes all of the bits and pieces he needs for the early lessons in his book without having to risk information overload by covering the nitty-gritty of those bits and pieces. It's classic chicken and egg. Stroustrup wants to teach those early lessons in a controlled manner by reducing the information load on the student until Stroustrup can cover the material required to actually understand the background details of those early lessons.
Great teaching strategy. In a way, the strategy is worth emulating in code: He's eliminated a problem by adding a layer of indirection.
But it can be a bad strategy in the programmer's real world of sliding ship dates, pointy-haired bosses, death marches, and lawsuits. You don't want to waste time fixing a non problem that didn't need to be there in the first place. Code that's not there has no bugs. Or is a bug, but that's another issue.
And Bjarne Stroustrup can get away with some stuff because he's Bjarne expletive deleted Stroustrup. He knows what he's doing. He's demonstrated that. He's probably considered, measured, and weighed the implications of his megaheader because he knows what they are. If he was worried that something in it was going to smurf over his students, he wouldn't have done it.
The first year programming student isn't Bjarne Stroustrup. Even if they have a brain the size of a planet, they lack the years of experience. It's usually the the stuff you don't know that you have to worry about, and Stroustrup's pool of "don't know" is going to be notably smaller.
There are all sorts of unsafe things that you can do when you know what you are doing and can honestly justify the doing. And as long as you take into account that you might not be the only person with a vested interest in the code. Your super-elegant-but-super-arcane solution isn't much if the coder who picks up your portfolio after you get hit by a bus can't read it. Your lovely code is going into the bin and your legacy will be, "What the smurf was that smurfing idiot trying to do with that smurf?" At the very least leave some notes.
Stroustrup also has page and word constraints that require him to compress the text in the printed edition. One Header to Rule Them All helps dramatically.
Your teacher has a similar problem with student overload, but probably doesn't have the print space constraints. For the snippets of code you've seen so far, all that has been required is the basic input and output that requires iostream. And probably string, but even I'll admit it'll be really hard to write the iostream header without it including string.
Soon you will start seeing #include <vector>, #include <fstream>, and #include<random>, as well as start writing your own headers.
Strive to learn to do it right, otherwise you have a nasty software engineering learning curve after graduation.
The include_std_facilities.h file, supplied with the books or accessible online, is like a shortcut to including multiple header files (if you include that file, looking at the source, it just includes some useful headers like so that you don't need to explicitly include them yourself).
Think of it as inviting your mother around to dinner. You invite her, and that inevitably implies that your dad (okay Im making assumptions), your sister and that annoying yappy dog of hers will automatically come for dinner too, without asking them explicitly.
It's not really a great practise, but I presume the author has their reasons.
Your teacher is correct, the minimal code will often include iostream so that you can output to the terminal. However, and this is something I have to stress, using namespace std is bad practice. You can access std functionality by explicitly using std:: - for example:
std::cout << "hello world!" << std::endl;
Working outside of the std namespace is beneficial for a multitude of reasons. You can find these by a bit of googling.
My guess is the author of the book does it to keep the code examples shorter, not as an example of exemplary style. No need to put boiler plate text in every example.
For my take, putting a bunch of includes into a header file that everybody includes (that isn't a precompiled header) can slow compilation down considerably (not only having to seek and load each file, but to check dependencies, etc), particularly if you have an overzealous IT department that insists on live scanning every file access.

Is it possible to package C++ libraries?

I know in C++ you have to use the "#include" statement to include libraries and headers, like:
#include <iostream>
#include <string>
#include "my_header.h"
But after some time, that can look very ugly, having a load of includes in your files. I wanted to know if there is some way where we can call just 1 file to include EVERYTHING we'll need in the C++ project. Kind of like...
"include_everything.h"
#include <iostream>
#include <string>
#include "header1.h"
#include "header2.h"
and then in our .cpp file, could we go?
#include "include_everything.h"
// write code here...
If it is possible, is it lawful? Does it abide by the C++ coding laws?
Thanks in advance,
Gumptastic
If that is the only rule you decide not to follow you will probably be fine. But, depending on what some of those headers contain (macros, #defines, etc) you could get a horrible mess in the end.
I've seen cases where people included what they thought they needed (often ended up being much more than was needed as they failed to consider forward declarations). On a large software project, each CPP file ended up loading nearly every include file anyway (due to chaining). Often the same file would get loaded multiple time and only excluded once the #ifndef statement at the top was triggered. The OS ended up opening over 100k files for each compile even though only there were only 50k files in the project. In a horrible situation like that it might help.
It can save time for developers as they, generally, won't have to search out where something is defined and add it to their include list for every file they work on. Do it once and forget. Let the compiler tell you if a new file needs to be added to 'everything'.
Aside from the macro problem you might run into issues with overlapping names and such if you don't properly use namespaces. Also, template classes often have real code in the header file. This can create churn.
It might also cause problems if people are using global variables and they are eclipsing local variables. It might be hard to figure out where that global 'i' is defined and being pulled in from if you have to search all files in 'everything' instead of just the files in your include list.
You can do it. If its just you and includes bug you, go for it. If you are your buds are doing something, sure. You are going to serious looks from people if you try to do this on a medium sized project or larger.
At best, I wouldn't suggest using to go beyond grouping tightly bundled headers together into a more coherent API.
You can do this, but it might affect compilation time.
The C(++) #include compiler instruction means nothing more than "Before you compile, copy and paste the content of that file here". That means when you include more headers than necessary, it will take a bit longer to compile each source file. But when that's not a concern for you, go ahead.
Yes, you can do it. You may recursively include headers.
However, If you are including so many headers that this is a problem, either you're including ithings you don't need to include or your source files are way too expansive.
Consequently, it's very rare to do this and I'd go so far as to consider it a big code smell. The only time you really want to do it is when you're going to precompile that include_everything.h.

Why does Xcode 4 include iostream in every header?

I noticed that newly created CPP files in Xcode ~4 all #include <iostream>. I never use any iostream functionality, so usually strip them out (hearing they can gradually slow build times from the Google blink team blog). Are there any useful generic functions of iostream that make including it all the time valuable? Such as instrumentation or reflection features that not having it everywhere would break?
It seems like a bold step to add everywhere - especially given how conservative many groups software engineering! - so feel there must be something important I'm missing.
Does anyone know the reason why this header has become so important it must be everywhere?
I sign juanchopanzas statement: There is no header that needs to be included everywhere. Each #include should only be in a file when it is really needed.

Include everything, Separate with "using"

I'm developing a C++ library. It got me thinking of the ways Java and C# handle including different components of the libraries. For example, Java uses "import" to allow use of classes from other packages, while C# simply uses "using" to import entire modules.
My questions is, would it be a good idea to #include everything in the library in one massive include and then just use the using directive to import specific classes and modules? Or would this just be down right crazy?
EDIT:
Good responses so far, here are a few mitigating factors which I feel add to this idea:
1) Internal #includes are kept as normal (short and to the point)
2) The file which includes everything is optionally supplied with the library to those who wish to use it3) You could optionally make the big include file part of the pre-compiled header
You're confusing the purpose of #include statements in C++. They do not behave like import statements in Java or using statements in C#. #include does what it says; namely, loads and parses the entire indicated file as part of the current translation unit. The reason for the separate includes is to not have to spend compilation time parsing the entire standard library in every file. In contrast, the statements you're trying to make #include behave like are merely for programmer organization purposes.
#include is for management of the compilation process; not for separating uses. (In fact, you cannot use seperate headers to enforce seperate uses because to do so would violate the one definition rule)
tl;dr -> No, you shouldn't do that. #include as little as possible. When your project becomes large, you'll thank yourself when you're not waiting many hours to compile your project.
I would personally recommend only including the headers when you need them to explicitly show which functionalities your file requires. At the same time, doing so will prevent you from gaining access to functionalities you might no necessarily want, e.g functions unrelated to the goal of the file. Sure, this is no big deal, but I think that it's easier to maintain and change code when you don't have access to unnecessary functions/classes; it just makes it more straightforward.
I might be downvoted for this, but I think you bring up an interesting idea. It would probably slow down compilation a bit, but I think the concept is neat.
As long as you used using sparingly — only for the namespaces you need — other developers would be able to get an idea of what classes were used in a file by glancing at the top. It wouldn't be as granular as seeing a list of #included files, but is seeing a list of included header files really very useful? I don't think so.
Just make sure that all of the header files all use inclusion guards, of course. :)
As said by #Billy ONeal, the main thing is that #include is a preprocessor directive that causes a "^C, ^V" (copy-paste) of code that leads to a compile time increase.
The best considered policy in C++ is to forward declare all possible classes in ".h" files and just include them in the ".cpp" file. It isolates dependencies, as a C/C++ project will be cascadingly rebuilt if a dependent include file is changed.
Of course M$ compilers and its precompiled headers tend to do the opposite, enclosing to what you suggest. But anyone that tried to port code across those compilers is well aware of how smelly it can go.
Some libraries like Qt make extensive use of forward declarations. Take a look on it to see if you like its taste.
I think it will be confusing. When you write C++ you should avoid making it look like Java or C# (or C :-). I for one would really wonder why you did that.
Supplying an include-all file isn't really that helpful either, as a user could easily create one herself, with the parts of the library actually used. Could then be added to a precompiled header, if one is used.