I have a very large Native C++ project with hundreds of classes each defined in their own .cpp and .h file. Nothing weird here. I have all of the classes declared in my pre-compiled header stdafx.h file and also included in the stdafx.h file as shown below (to allow Foo to reference Bar AND Bar to reference Foo).
Is this organization bad practice?
Essentially, all classes are declared and included in every object. I assume the compiler is not going to generate overhead binary by having things included which are not necessary to compiling the particular .cpp object file. As of now I'm not having any problem with compile time either. I'm just wondering if this is a bad organization for the code.
I like this layout because the stdafx.h file is essenetially a code map since all classes are declared there and it reveals the nested namespaces is an easy to read format. It also means that my individual class .h files don't require several include statements which means less code for me to maintain when making changes to filenames or directories.
stdafx.h:
#pragma once
namespace MyProject
{
class Foo;
class Bar;
}
#include "Foo.h"
#include "Bar.h"
foo.h:
#pragma once
namespace MyProject
{
class Foo
{
// Declare class members, methods, etc
}
}
foo.cpp:
#include "stdafx.h"
namespace MyProject
{
class Foo
{
// Define class members, methods, etc
}
}
In my mind there are 4 key factors here:
Compile Time: Keep in mind that a #include "x.h" embeds all the code in x.h at that line. If the project is going to grow substantially have a care for how you're going to impact future compile times.
Foo and Bar Stability: If Foo and Bar are changing you're going to have to keep recompiling stdafx.h
Circular Definitions: You will no longer be able to break circular definitions with forward declares.
Explicit Dependencies: You won't be able to look at your includes and know what is used in a particular file.
If you feel your pros outweigh the cons listed here, there's nothing illegal about what you're doing so go for it!
A header should include everything it needs, no more, no less.
That's a basic requirement for ease-of-use and simple encapsulation.
Your example explicitly fail that point.
To detect violations, always include the corresponding header first in the translation-unit.
This is slightly modified if you use precompiled headers, in which case they have to be included first.
Pre-compiled headers should only include rarely changing elements.
Any change to the pre-compiled header or its dependencies will force re-compilation of everything, which runs counter to using one at all.
Your example fails that point too.
All in all, much to improve.
Related
I have a code that contains huge number of cpp / header files. My problem now is, that because many include each other, I occasionally get into a situation that my code doesn't compile, unless I reorder the #include directives in random files, which is now necessary basically with creation of any other header file.
This is really very annoying; is there any tip how should I write my c++ code in order to prevent complications with #include? I would prefer to split my source code to as many files as possible so that cooperation with other programmers (using git or svn) is easier (more files == lower number of edit conflicts).
One of things that help me now is forward declaration, when I declare the classes from other headers into other files. That helps sometimes, but doesn't resolve all issues; sometimes I just need to change order of #includes in random header files or merge multiple files.
Not a panacea, but the following guideline helps me a lot.
Assuming your code is composed of files like MyClassXyz.cpp with corresponding MyClassXyz.h, one class per source file, every cpp-file should include its corresponding header file first. That is, MyClassXyz.cpp must start with the following line:
// (possibly after comments)
#include "MyClassXyz.h"
This ensures that MyClassXyz.h includes all header files (or forward declarations) necessary for its compilation.
I often see code that uses an opposite convention (#includeing most general header files first), for example, MyClassXyz.cpp starts with
#include <vector>
#include <iosfwd>
#include "blah.h"
#include "mytypes.h"
#include "MyClassXyz.h"
And MyClassXyz.h "goes straight to the point" using stuff defined in the additional headers:
#pragma once
// "#include <vector>" missing - a hidden error!
// "#include <iosfwd>" missing - a hidden error!
class MyClassXyz
{
std::vector<int> v;
friend std::ostream& operator<<(...);
...
}
While this compiles OK, it gives enormous headaches of the type you describe, when trying to use the class MyClassXyz in some other source file.
Suppose I have a class called CameraVision in the file CameraVision.cpp.
The constructor for this class takes in a vector of IplImage* (IplImage is a C struct that represents an image in OpenCV). I need to #include opencv.h either in CameraVision.hpp or CameraVision.cpp.
Which is better and why? (#including these in CameraVision.hpp or in CameraVision.cpp?)
Also, where should I #include STL <vector>, <iostream>, etc. ?
Suppose the client of CameraVision.cpp also uses <vector> and <iostream>. The client would obviously #include CameraVision.hpp (since he is a client of CameraVision). Should the client of CameraVision.cpp also #include , <iostream>, etc. if they have already been #include'd in CameraVision.hpp? How would the client know this?
The rule here is: Limit scope. If you can get away with having the include in the implementation file only (e.g. by using a forward declaration, including <iosfwd> etc.), then do so. In public interfaces, i.e. the headers that your clients will include to use a library of your making, consider using the PIMPL pattern to hide any implementation details.
The benefits:
1) Clarity of code. Basically, when somebody is looking at a header file, he is looking for some idea of what your class is about. Every header included adds "scope" to your header: Other headers to consider, more identifiers, more constructs. In really bad code, every header includes yet more headers, and you cannot really understand one class without understanding the whole library. Trying to keep such dependencies at a minimum makes it easier to understand the interface of a class in isolation. ("Don't bother what IplImage actually is, internally, or what it can do - at this point all we need is a pointer to it").
2) Compile times. Since the compiler has to do the same kind of lookup as described in 1), the more includes you have in header files, the longer it takes to compile your source. In the extreme, the compiler has to include all header files for every single translation unit. While the resulting compile time might be acceptable for a once-over compilation, it also means that it has to be re-done after any change to a header. In a tight edit - compile - test - edit cycle, this can quickly add up to unacceptable levels.
Edit: Not exactly on-topic, but while we're at it, please don't use using in header files, because it's the opposite of limiting scope...
To avoid extra includings, you should use #include in implementation (.cpp) files in all cases, except in situations when names that you are importing, used in prototypes or declarations, which your module exports.
For example:
foo.h:
#ifndef _FOOBAR_H_
#define _FOOBAR_H_
#include <vector>
void foo();
std::vector<int> bar();
#endif // _FOOBAR_H_
foo.cpp:
#include "foo.h"
#include <iostream>
void foo() {
std::cout << "Foo";
}
std::vector<int> bar() {
int b[3] = {1, 2, 3};
return std::vector<int>(b, b+3);
}
If a type is used/referenced only within the implementation file, and not in the header file, you should #include only in the implementation file, upholding the principle of limited scope.
However, if your header file references a type, then your header file should #include that type's header file. The reason being that your header file should be able to be completely understood and have everything it needs when it is #included.
One justification for this perspective is not just for building/compiling, but also tooling. Your development environment may parse header files to provide you with type assistance (e.g. Intellisense, Command Completion, etc...) which may require complete type information to work properly.
Another justification is if your header file is used by another party, that that party has enough information about your types to make use of your code. And they should not have to #include several files to get one type to compile.
You should not #include a type's header file in another type's header file simply to avoid having to #include two files in the implementation file. Instead, a third header file should be made for the purpose of aggregating those types.
If I have a project with
main .cpp
Knife .h and .cpp
Cucumber .h and .cpp
and I want to use Knife's members in Cucumber, does it matter whether I use the following:
#include "Knife.h"
#include <iostream>
using namespace std;
in Cucumber.h or Cucumber.cpp (assume that Cucumber.cpp already has an include for Cucumber.h)?
My recommendation is to minimize the number of files included in the header files.
So, if I have the choice, I prefer to include in the source file.
When you modify a header file, all the files that include this header file must be recompiled.
So, if cucumber.h includes knife.h, and main.cpp includes cucumber.h, and you modify knife.h, all the files will be recompiled (cucumber.cpp, knife.cpp and main.cpp).
If cucumber.cpp includes knife.h and main.cpp includes cucumber.h, and you modify knife.h, only cucumber.cpp and knife.cppwill be recompiled, so your compilation time is reduced.
If you need to use knife in cucumber you can proceed like this:
// Cucumber.hpp
#ifndef CUCUMBER_HPP
#define CUCUMBER_HPP
class Knife;
class Cucumber
{
public :
///...
private :
Knife* myKnife
}
#endif
//Cucumber.cpp
#include "Cucumber.hpp"
#include "Knife.hpp
// .. your code here
This "trick" is called "forward declaration". That is a well-known trick of C++ developers, who want to minimize compilation time.
yes, you should put it in the .cpp file.
you will have faster builds, fewer dependencies, and fewer artifacts and noise -- in the case of iostream, GCC declares:
// For construction of filebuffers for cout, cin, cerr, clog et. al.
static ios_base::Init __ioinit;
within namespace std. that declaration is going to produce a ton of (redundant) static data which must be constructed at startup, if Knife.h is included by many files. so there are a lot of wins, the only loss is that you must explicitly include the files you actually need -- every place you need them (which is also a very good thing in some regards).
The advice I've seen advocated was to only include the minimum necessary for a given source file, and to keep as many includes out of headers as possible. It potentially reduces the dependencies when it comes time to compile.
Another thing to note is your namespace usage. You definitely want to be careful about having that sort of thing in a header. It could change namespace usage in files you didn't plan on.
As a general rule, try to add your includes into the implementation file rather than the header for the following reasons:
Reduces potential unnecessary inclusion and keeps it to only where needed.
Reduces compile time (quite significantly in some cases I've seen.) Avoids over exposing implementation details.
Reduces risk of circular dependencies appearing.
Avoids locking users of your headers into having to indirectly include files that they may not want / need to.
If you reference a class by pointer or reference only in your header then it's not necessary to include the appropriate header; a class declaration will suffice.
Probably there are quite a few other reasons - the above are probably the most important / obvious ones.
I have a theory question rather than an error report.
I'm a rookie C++ programmer, trying to promote that away
Using the VC++ VS2008 compiler
I am often finding myself wondering WHY I want to take some actions in header files.
For example look at this code block:
#include "DrawScene.h"
#include "Camera.h"
#include "Player.h"
#include "Grid.h"
#include "InputHandler.h"
#include "GameState.h"
class Controller
{
public:
private:
public:
Controller();
~Controller(){}
void Update();
private:
};
And the hooked up CPP file , controller.cpp along with it
#include "stdafx.h"
#include "glut.h"
#include "Controller.h"
#include <iostream>
Grid* grid_ptr = new Grid();
InputHandler* inputHandler_ptr = new InputHandler();
DrawScene* drawScene_ptr = new DrawScene();
GameState* gameState_ptr = new GameState();
Controller::Controller()
{
}
void Controller::Update()
{
}
What is a good way to decide which includes go where? So far I've been going with the " whatever works" method but I find it somewhat unprofessional.
Now even though you can say my code has X syntax errors and design flaws, please do, but the focal point I would appreciate that information remains on the use of .h VS .cpp files.
Why is there even such a design? And what are the pits and traps to always be treading lightly around when making any kind of OOP based C++ program?
What sparked this question for me btw was that I wanted to notify the reader of the header file there will be objects stored in the controller but assigning these uninitialized objects seemed impossible without making them static.
Note: I stem from C# --> C++ , might help to know. That's kind of my perspective on code at this point.
Thank you in advance for you efforts!
EDIT: 26/08/2010 18:16
So the build time is the essence of good includes. Is there more to be cautious about?
This is my personal opinion rather than a consensus best practice, but what I recommend is: in a header file, only include those headers that are necessary to make the contents of the header file compile without syntax errors. And if you can use forward declarations rather than nested inclusions, do so.
The reason for this is, in C++ (unlike C#, iiuc) there's no export control. Everything you include from a header will be visible to the includers of the header, which could be a whole lot of junk that users of your interface should not see.
Generally speaking headers should reside in the cpp file. For standard library includes (and possibly 3rd library includes) you can stick them in headers. However headers defined specifically for your project should go in cpp files whenever possible.
The reason for this is compilation time and dependency issues. Any time you change a header file, the compiler will have to recompile every source file that includes it. When you include a header file in another header file, then the compiler has to recompile every cpp file that includes either header file.
This is why forward declaration and the PIMPL (Pointer to IMPLementation, or opaque pointer) pattern are popular. It allows you to shift at least some of the changes/implementation out of the header file. For example:
// header file:
class SomeType;
class AnotherType
{
private:
SomeType *m_pimpl;
};
doesn't require you to include "sometype.h" whereas:
// header file
class AnotherType
{
private:
SomeType m_impl;
};
does. EDIT: Actually, you don't need to include "sometype.h" in the "anothertype.h" if you ALWAYS include "sometype.h" before "anothertype.h" in EVERY cpp file that includes "anothertype.h".
Sometimes it can be difficult to move a header file to the cpp file. At that point you have a decision - is it better to go through the effort of abstracting the code so you can do so, or is it better to just add the include?
Only include headers in another header if absolutely necessary. If the header can go solely in the source file then that's the best place. You can use forward declarations of classes in the header if you are only using pointers and references to them. Your DrawScene, GameState, Grid and InputHandler classes looks like they might fall into this category.
Note that C++ as a language does not care about the distinction between headers and source files. That's just an extremely common system used by developers to maintain their code. The obvious advantage of using headers is to avoid code duplication and helps, to an extent, to enforce the one-definition-rule for classes, templates and inline functions.
Avoid putting too many (read, any unnecessary) #includes in your .h file. Doing so can lead to long build times, as e.g. whenever you change Camera.h you will have changed Controller.h, so anything that includes Controller.h will need to be rebuilt. Even if it is only a comment that has changed.
Use forward declarations if you are only storing pointer members, then add the #includes to the cpp file.
Theoretically, .h files contain just the interface, and .cpp files, the implementation. However, since private members are arguably implementation, and not interface, this is not strictly true, hence the need for forward declarations in order to minimise unnecessary rebuilds.
It is possible, in C++, to include the whole implementation inline in the class definition, file, much as you might with Java, but this really breaks the .h/.cpp interface/implementation rule.
Header files contain declarations of functions, classes, and other objects, whereas cpp files are meant for implementing these previously declared objects.
Header files exist primarily for historical reasons. It's easier to build a C++ compiler if the definitions of all functions, classes, etc to be used by your code are given before you actually call them.
Usually you use cpp for your implemenation. Implementing functions in header files automatically inlines them, so unless these are very small and / or very frequently called, this is usually not what you want.
I have a question regarding "best-practice" when including headers.
Obviously include guards protect us from having multiple includes in a header or source file, so my question is whether you find it beneficial to #include all of the needed headers in a header or source file, even if one of the headers included already contains one of the other includes. The reasoning for this would be so that the reader could see everything needed for the file, rather than hunting through other headers.
Ex: Assume include guards are used:
// Header titled foo.h
#include "blah.h"
//....
.
// Header titled bar.h that needs blah.h and foo.h
#include "foo.h"
#include "blah.h" // Unnecessary, but tells reader that bar needs blah
Also, if a header is not needed in the header file, but is needed in it's related source file, do you put it in the header or the source?
In your example, yes, bar.h should #include blah.h. That way if someone modifies foo so that it doesn't need blah, the change won't break bar.
If blah.h is needed in foo.c but not in foo.h, then it should not be #included in foo.h. Many other files may #include foo.h, and more files may #include them. If you #include blah.h in foo.h, then you make all those files needlessly dependent on blah.h. Needless dependencies cause lots of headaches:
If you modify blah.h, all those files must be recompiled.
If you want to isolate one of them (say, to carry it over to another project or build a unit test around it) you have to take blah.h along.
If there's a bug in one of them, you can't rule out blah.h as the cause until you check.
If you are foolish enough to have something like a macro in blah.h... well, never mind, in that case there's no hope for you.
The basic rule is, #include any headers that you actually use in your code. So, if we're talking:
// foo.h
#include "utilities.h"
using util::foobar;
void func() {
foobar();
}
// bar.h
#include "foo.h"
#include "utilities.h"
using util::florg;
int main() {
florg();
func();
}
Where bar.h uses tools from the header included twice, then you should #include it, even if you don't necessarily have to. On the other hand, if bar.h doesn't need any functions from utilities.h, then even though foo.h includes it, don't #include it.
The header for a source file should define the interface that the users of the code need to use it accurately. It should contain all that they need to use the interface, but nothing extra. If they need the facility provided by xyz.cpp, then all that is required by the user is #include "xyz.h".
How 'xyz.h' provides that functionality is largely up to the implementer of 'xyz.h'. If it requires facilities that can only be specified by including a specific header, then 'xyz.h' should include that other header. If it can avoid including a specific header (by forward definition or any other clean means), it should do so.
In the example, my coding would probably depend on whether the 'foo.h' header was under the control of the same project as the 'blah.h' header. If so, then I probably would not make the explicit second include; if not, I might include it. However, the statements above should be forcing me to say "yes, include 'foo.h' just in case".
In my defense, I believe the C++ standard allows the inclusion of any one of the C++ headers to include others - as required by the implementation; this could be regarded as similar. The problem is that if you include just 'bar.h' and yet use features from 'blah.h', then when 'bar.h' is modified because its code no longer needs 'blah.h', then the user's code that used to compile (by accident) now fails.
However, if the user was accessing 'blah.h' facilities directly, then the user should have included 'blah.h' directly. The revised interface to the code in 'bar.h' does not need 'blah.h' any more, so any code that was using just the interface to 'bar.h' should be fine still. But if the code was using 'blah.h' too, then it should have been including it directly.
I suspect the Law of Demeter also should be considered - or could be viewed as influencing this. Basically, 'bar.h' should include the headers that are needed to make it work, whether directly or indirectly - and the consumers of 'bar.h' should not need to worry much about it.
To answer the last question: clearly, headers needed by the implementation but not needed by the interface should only be included in the implementation source code and absolutely not in the header. What the implementation uses is irrelevant to the user and compilation efficiency and information hiding both demand that the header only expose the minimum necessary information to the users of the header.
Including everything upfront in headers in C++ can cause compile times to explode
Better to encapsulate and forward declare as much as possible. The forward declarations provide enough hints to what is required to use the class. Its quite acceptable to have standard includes in there though (especially templates as they cannot be forward declared).
My comments might not be a direct answer to your question but useful.
IOD/IOP encourages that put less headers in INTERFACE headers as possible, the main benefits to do so:
less dependencies;
smaller link-time symbols scope;
faster compiling;
smaller size of final executables if header contains static C-style function definitions etc.
per IOD/IOP, should interfaces only be put in .h/.hxx headers. include headers in your .c/.cpp instead.
My Rules for header files are:
Rule #1
In the header file only #include class's that are members or base classes of your class.
If your class has pointers or references used forward declarations.
--Plop.h
#include "Base.h"
#include "Stop.h"
#include <string>
class Plat;
class Clone;
class Plop: public Base
{
int x;
Stop stop;
Plat& plat;
Clone* clone;
std::string name;
};
Caviat: If your define members in the header file (example template) then you may need to include Plat and Clone (but only do so if absolutely required).
Rule #2
In the source put header files from most specific to least specific order.
But don't include anything you do not explicitly need too.
So in this case you will inlcude:
Plop.h (The most specific).
Clone.h/Plat.h (Used directly in the class)
C++ header files (Clone and Plat may depend on these)
C header files
The argument here is that if Clone.h needs map (and Plop needs map) and you put the C++ header files closer to the top of the list then you hide the fact that Clone.h needs map thus you may not add it inside Clone.h.
Rule #3
Always use header guards
#ifndef <NAMESPACE1>_<NAMESPACE2>_<CLASSNAME>_H
#define <NAMESPACE1>_<NAMESPACE2>_<CLASSNAME>_H
// Stuff
#endif
PS: I am not suggesting using multiple nested namespaces. I am just demonstrating how I do if I do it. I normal put everything (apart from main) in a namespace. Nesting would depend on situation.
Rule #4
Avoid the using declaration.
Except for the current scope of the class I am working on:
-- Stop.h
#ifndef THORSANVIL_XXXXX_STOP_H
#define THORSANVIL_XXXXX_STOP_H
namespace ThorsAnvil
{
namespace XXXXX
{
class Stop
{
};
} // end namespace XXXX
} // end namespace ThorsAnvil
#endif
-- Stop.cpp
#include "Stop.h"
using namespace ThorsAnvil:XXXXX;