If I am creating a class with small functions that don't do much, is it acceptable to just put them all into the header file? So for a particular class, it's only just the .h with no .cpp to go with it.
Yes, that's acceptable. It will certainly compile. But also, if it makes the code organization cleaner, then that can be good. Most template definitions are already like this out of necessity, so you aren't doing anything unheard of. There can be some drawbacks of that class relies on other classes though. If you end up having to include the whole definition in other files that use the class, it may incur additional compile time compared to only having a brief class declaration.
You can measure your compilation times if this seems to be a real concern.
If you can get a copy, The c++ Programming Language (and many other books) have a detailed section about source code organization and the specific benefits of separating code into .h and .cpp files.
It depends what you are aiming for.
For a pet project, it's acceptable, but then anything is really.
For a real project, you need to ask yourself a number of questions:
do you have few dependencies ? (yes)
is your logic / implementation likely to change often ? (no, or see next question)
how much depends on this class ? (not much or much but it won't change)
If the responses satisfy you, then go ahead.
It is mainly a matter of dependency management. By putting the methods definition within the header, they are likely to get inlined by the compiler, which means that each time they change you'll have to recompile everything that depends on this class.
Templates do so, however templates generally have few dependencies (other includes) and you're relatively forced to proceed like so (though you can externalized non-template dependent code to cut down on dependencies).
For real big projects where dependency management is foremost, then I would advise against. In those projects a stable ABI and the ability to promote binary compatible changes are life-savers in case of issue and they are well worth the "slight" inconvenience for the developer.
In any case, please don't define the methods in the midst of the class. Even inlined you can define them after the class declaration. This makes it easier for people reading it (yourself in a few months) to get a grasp of the interface quickly.
Yes, it is acceptable. Moreover, if you do templates and you don't have a compiler with export support then you don't have a choice.
However, note that it can increase dependencies and thus make compilation slower.
It would be fine if you will use that header file in your future codes or projects, and if you want to share it with the others.
Depends on how you're linking. To avoid having to see messages such as redefinition of blah, previous definition in file blah.h on line 13 just put everything but the declaration in a .cpp.
Related
C++ was the the first language I've learnt so dividing source code into .h and .cpp files seemed obvious - but having learnt C# and Java they now appear to me terribly clumsy. They might have been useful back in the 60s, maybe still even in 80s, but in the era of modern tools, such as IDEs with section folding, and documentation generators, they seem obsolete.
Anyway, my question is: is there a tool which makes the presence of these two kind of files transparent to the programmer? For example by letting the coder write the definition of a method seemingly in the header file but actually saving it to the .cpp file?
(I know one can try to write a C++ program solely in header files but AFAIK this is not considered best practice, makes the program build even longer and makes it virtually impossible for two classes to reference each other.)
The discussion that I am seeing in the question, comments and the comments to the other answer seem to focus on the textual representation of the components. From the point of view of plain text, it makes sense to remove the headers altogether.
On the other hand, there is a second level to the separation of headers and cpp files, which is separating the interface from the implementation, and in doing so, removing implementation details from the interface.
This happens in different ways, in the simplest level how you implement a particular piece of functionality is irrelevant to the users of your component[*]. In many cases, you can have more types and functions in the .cpp file that are used just as details of implementation. Additionally, if you decide to implement a particular functionality directly or by depending on another library is a detail of implementation and should not leak to your users.
That separation might or might not be easy to implement in a tool that managed the separation of files automatically, and cannot be done by those that like the use of header only libraries.
Where some of you are claiming that there is no point in having to Go to definition, and would like to see the code altogether, what I see is the flexibility of deciding what parts of your component are details that should not be known by users. In many IDEs (and, heck, even in vim) there is a single keystroke combination that will take you from one to the other. In IDEs you can refactor the signature of the function and have the IDE apply the changes to both the header and the implementation (sometimes even to the uses)...
If you were to have a tool provide a unified view of both the header and implementation, it would probably be much harder to make the tool knowledgable of what parts of the code you are writing are part of the interface or the implementation, and the decisions that the tool might have could have an impact on the generated program.
The separate compilation model has its disadvantages but also advantages, and I feel that the discussion that is being held here is just scratching the surface of deeper design decisions.
[*] There seems to be quite a few people that believe that each class should have its own header and .cpp files, and I disagree, each header represents a component that might be a single class, or multiple classes and free functions the separation of code in files is part of the design, and in a single component you might have one or more public types together with possibly none or more internal types.
I don't know of any that makes the division into source/header completely transparent.
I do, however, know of some that make it considerably easier to handle. For example, Visual Assist X will let write your entire class in a header, then select member functions, and move them to a source file (i.e., a .cpp file).
That's not a complete cure (by any means), but it can/does make them much more bearable anyway.
Personally, I think it would be interesting to get rid of files completely, and instead use something like a database directly -- i.e., you have a database of functions, where the source code to that function is one column, object code another, internal compiler information about how to use it yet another, and so on. This would also make integrating version control pretty straightforward (basically just a stored transaction log).
I, for one, like the header files in C++, because they can serve as a "table of contents" of a sort, which gives you a quick overview of a class. This is, of course, assuming that you keep your headers short, and put the implementation of most functions into the .cpp.
Also, you can get plugins for Visual Studio that will move the implementation of a member function from the header into a .cpp for you. That, plus the "go to definition" and "go to declaration" commands in Visual Studio make headers very helpful for navigating a large code base.
Headers are pretty fundamental to the current compilation model of C++. I think there are things that would be a bit difficult to express without exposing the programmer directly to the header/cpp split. For example, in certain circumstances there's a significant difference between:
// header
class Foo {
Foo() = default;
}
and
// header
class Foo {
Foo();
};
// cpp
Foo::Foo() = default;
Despite that I think it would be worthwhile to think about improving the compilation model or making it easier to deal with.
For example, I can imagine a 'code bubbles' style IDE where the programmer writes definitions in code bubbles, and then groups bubbles together into translation units. The programmer would mark definitions as 'exported' to make them available to other TUs and for each TU he'd select exported items from other units to import. And all the while the IDE is maintaining it's own code bubble representation of the program, and when you build it generates the actual cpp files necessary for passing off to the compiler, creating forward declarations, etc. as needed. The cpp files would just be an intermediate build product.
There would be subtleties like the one I showed above though, and I'm not sure how the IDE I described would deal with that.
Just a style question...
I'm a lowly indie game dev working by myself, and I developed what I have been told is a 'bad' habit of writing whole classes in my headers. Some of the benefits I know .h/.cpp file combos have are they allow code to be split into compilation chunks that won't need recompiled so long as they remain unchanged. And allows for splitting interface from implementation.
However, neither of those things are of any benefit to me, since I tend to favour having my implementation in a spot where I can easily improve it, change it, read it. And my compile times are nigh instantaneous (2-4 seconds, 15 if I updated SFML or Box2D to their latest versions and they need recompiled too)
Coding like this has been saving me a very noticeable amount of time I think, and since there are less files, my code feels less 'overwhelming' to me.
But in light of that, and in general, is there any compelling reason to follow the "file.cpp" for every "file.h" setup for a small project where compile time and interface/implementation separation are not priorities?
is there any compelling reason to follow the "file.cpp" for every "file.h" setup for a small project where compile time and interface/implementation separation are not priorities?
Nope; there's nothing wrong with defining classes and functions in header files, especially not in small projects where compile times aren't a concern.
For what it's worth, my current, in-progress hobby project has 33 header files and a single .cpp file (not including unit tests). That is largely due to just about everything being a template, though.
If you have a huge software project or if you need to encapsulate your code into a library and actually need the modularity, then it might make sense to split code out of a header file. If you want to hide some implementation detail (e.g., if you have some ugly header that you don't want to include elsewhere in your project--WinAPI headers, for example), then it makes sense to split code into a separate source file to hide those details. Otherwise, it may just be a lot of work for not a lot of gain.
I think both compile time and interface/implementation separation are good reasons. Even if the former is not a problem right now, in most decent-sized projects, it does become a problem.
But, since you asked for other reasons, I think a big one is that it reduces dependencies. The implementation of your class probably requires more #includes than the interface. But if you put the implementation in the header file, you drag along those dependencies with the header. Then every other file that includes that also has those dependencies.
There is no one-size-fits-all rule, though. And some classes (especially "small" ones) are probably best placed entirely in a header.
What you're doing sounds sensible for your situation. Two other potential issues:
one definition rule
testing
If you've got just one cpp file and a couple dozen headers, then you can afford to be careless about the one definition rule (assuming you have include guards). This could bite you if you one day find a need to move to compiling/linking the project as a number of translation units. That might happen in not-so-obvious ways, such as wanting to let other people supply a library that they're to build using a couple of your headers. implicitly (defined inside the class) or explicitly (using the keyword) inline functions will be ok, but beware others. Usual rules for variables etc..
For testing: sometimes it helps to have at least a token .cpp file that includes the .h and gets compiles, just so you get some early warning if the contents of one header can't "stand alone", probably due to a forgetten #include. If you have per-header test .cpp files then that kills two birds etc.. If you don't want testing at that level and are happy to clean up any minor dependency bugs reactively then might as well forget it.
I'm using C++ and I'm considering putting my function implementation into .h. I know that .h file is for definitions and .cpp is for implementations but how splitting all files into headers and sources will benefit me. Well if my aim would be to create static or dynamic library than of course that would make a difference but I am creating this code for myself and not planning to make a library out of it. So is there any other benefit from splitting source from definition?
The obvious goal is to reduce coupling : as soon as you change a header file, anything that includes it must be recompiled. This can rapidly have a strong impact on compilation times (even in a small project).
You can put almost all code into .h file, it will be header-only library. But if you want more faster partial recompilation, or if you want put some code to shared library - you should create .cpp files.
Depending on the size of your project it will save you compile time and make it possible to know all ressources etc. (unless you put everything into one single file).
The better your header files are organized the less work your compiler has to do to apply changes. Also looking in a small header file to look up some forgotten parameter information is a lot easier than scrolling through a hole cpp file.
One other obvious improvement is in avoiding re-compiling the code for your function in each file that uses it, instead compiling it once and using it where needed.
Another is that it follows convention (and the standard's one definition rule), so others will find it much easier to deal with and understand.
It depends on the size of the project. Up to about 500 LOC,
I tend to put everything in a single file, with the function
definitions in the class. Except that up to about 500 LOC,
I generally use a simpler language than C++; something like AWK.
As soon as the code gets big enough to warrent several source
files, it's definitely an advantage to put as little as possible
in the header, and that means putting all of the function
definitions in the source files. And as soon as the classes
become non-trivial, you probably don't want the function
definitions in the class itself, for readability reasons.
--
James Kanze
I love the concept of DRY (don't repeat yourself [oops]), yet C++'s concept of header files goes against this rule of programming. Is there any drawback to defining a class member entirely in the header? If it's right to do for templates, why not for normal classes? I have some ideas for drawbacks and benefits, but what are yours?
Possible advantages of putting everything in header files:
Less redundancy (which leads to easier changes, easier refactoring, etc.)
May give compiler/linker better opportunities for optimization
Often easier to incorporate into an existing project
Possible disadvantages of putting everything in header files:
Longer compile/link cycles
Loss of separation of interface and implementation
Could lead to hard-to-resolve circular dependencies
Lots of inlining could increase executable size
Prevents binary compatibility of shared libraries/DLLs
Upsets co-workers who prefer the traditional ways of using C++
Well - one problem is that typically implementations change much more often than class definitions - so for a large project you end up having to recompile the world for every small change.
The main reason not to implement a class in the header file is: do the consumers of your class need to know its implementation details? The answer is almost always no. They just want to know what interface they can use to interact with the class. Having the class implementation visible in the header makes it much more difficult to understand what this interface is.
Beyond considerations of compactness and separating interface from implementation, there are also commercial motivations. If you develop a library to sell, you (probably) do not want to give away the implementation details of the library you are selling.
You're not repeating yourself. You only write the code once in one header. It is repeated by the preprocessor, but that's not your problem, and it's not a violation of DRY.
If it's right to do for templates, why not for normal classes
It's not really that it's the right thing to do for templates. It's just the only one that really works in general.
Anyway, if you implement a class in a header, you get the following advantages and disadvantages:
The full implementation is visible anywhere it is used, which makes it easy for the compiler to inline as necessary.
The same code will be parsed and compiled multiple times, leading to higher compile-times.
On the other hand, if everything is in headers, that may lead to fewer translation units, and so the compiler has to run fewer times. Ultimately, you might end up with a single translation unit, which just includes everything once, which can result in very fast compilations.
And... that's it, really.
Most of my code tends to be in headers, but that's because most of my code is templates.
The main disadvantage (apart from the lengthy builds) is there is no clear separation of the interface and implementation.
Ideally, you should not need to see the implementation of an intuitive, and well documented interface.
Not mentionned yet: virtual functions are instantiated for each include, so you can bloat your executable (I'm not sure whether this is true for all compilers).
There is an alternative:
Do a lot of stuff in classes declared in your source-file. 1 example is the pimpl-idiom, but there are also people who are afraid to declare classes out of the header-file. However, this makes sense for private classes.
For whatever reason, our company has a coding guideline that states:
Each class shall have it's own header and implementation file.
So if we wrote a class called MyString we would need an associated MyStringh.h and MyString.cxx.
Does anyone else do this? Has anyone seen any compiling performance repercussions as a result? Does 5000 classes in 10000 files compile just as quickly as 5000 classes in 2500 files? If not, is the difference noticeable?
[We code C++ and use GCC 3.4.4 as our everyday compiler]
The term here is translation unit and you really want to (if possible) have one class per translation unit ie, one class implementation per .cpp file, with a corresponding .h file of the same name.
It's usually more efficient (from a compile/link) standpoint to do things this way, especially if you're doing things like incremental link and so forth. The idea being, translation units are isolated such that, when one translation unit changes, you don't have to rebuild a lot of stuff, as you would have to if you started lumping many abstractions into a single translation unit.
Also you'll find many errors/diagnostics are reported via file name ("Error in Myclass.cpp, line 22") and it helps if there's a one-to-one correspondence between files and classes. (Or I suppose you could call it a 2 to 1 correspondence).
Overwhelmed by thousands lines of code?
Having one set of header/source files per class in a directory can seem overkill. And if the number of classes goes toward 100 or 1000, it can even be frightening.
But having played with sources following the philosophy "let's put together everything", the conclusion is that only the one who wrote the file has any hope to not be lost inside. Even with an IDE, it is easy to miss things because when you're playing with a source of 20,000 lines, you just close your mind for anything not exactly referring to your problem.
Real life example: the class hierarchy defined in those thousand lines sources closed itself into a diamond-inheritance, and some methods were overridden in child classes by methods with exactly the same code. This was easily overlooked (who wants to explore/check a 20,000 lines source code?), and when the original method was changed (bug correction), the effect was not as universal as excepted.
Dependancies becoming circular?
I had this problem with templated code, but I saw similar problems with regular C++ and C code.
Breaking down your sources into 1 header per struct/class lets you:
Speed up compilation because you can use symbol forward-declaration instead of including whole objects
Have circular dependencies between classes (§) (i.e. class A has a pointer to B, and B has a pointer to A)
In source-controlled code, class dependencies could lead to regular moving of classes up and down the file, just to make the header compile. You don't want to study the evolution of such moves when comparing the same file in different versions.
Having separate headers makes the code more modular, faster to compile, and makes it easier to study its evolution through different versions diffs
For my template program, I had to divide my headers into two files: The .HPP file containing the template class declaration/definition, and the .INL file containing the definitions of the said class methods.
Putting all this code inside one and only one unique header would mean putting class definitions at the beginning of this file, and the method definitions at the end.
And then, if someone needed only a small part of the code, with the one-header-only solution, they still would have to pay for the slower compilation.
(§) Note that you can have circular dependencies between classes if you know which class owns which. This is a discussion about classes having knowledge of the existence of other classes, not shared_ptr circular dependencies antipattern.
One last word: Headers should be self-sufficients
One thing, though, that must be respected by a solution of multiple headers and multiple sources.
When you include one header, no matter which header, your source must compile cleanly.
Each header should be self-sufficient. You're supposed to develop code, not treasure-hunting by greping your 10,000+ source files project to find which header defines the symbol in the 1,000 lines header you need to include just because of one enum.
This means that either each header defines or forward-declare all the symbols it uses, or include all the needed headers (and only the needed headers).
Question about circular dependencies
underscore-d asks:
Can you explain how using separate headers makes any difference to circular dependencies? I don't think it does. We can trivially create a circular dependency even if both classes are fully declared in the same header, simply by forward-declaring one in advance before we declare a handle to it in the other. Everything else seems to be great points, but the idea that separate headers facilitate circular dependencies seems way off
underscore_d, Nov 13 at 23:20
Let's say you have 2 class templates, A and B.
Let's say the definition of class A (resp. B) has a pointer to B (resp. A). Let's also say the methods of class A (resp. B) actually call methods from B (resp. A).
You have a circular dependency both in the definition of the classes, and the implementations of their methods.
If A and B were normal classes, and A and B's methods were in .CPP files, there would be no problem: You would use a forward declaration, have a header for each class definitions, then each CPP would include both HPP.
But as you have templates, you actually have to reproduce that patterns above, but with headers only.
This means:
a definition header A.def.hpp and B.def.hpp
an implementation header A.inl.hpp and B.inl.hpp
for convenience, a "naive" header A.hpp and B.hpp
Each header will have the following traits:
In A.def.hpp (resp. B.def.hpp), you have a forward declaration of class B (resp. A), which will enable you to declare a pointer/reference to that class
A.inl.hpp (resp. B.inl.hpp) will include both A.def.hpp and B.def.hpp, which will enable methods from A (resp. B) to use the class B (resp. A).
A.hpp (resp. B.hpp) will directly include both A.def.hpp and A.inl.hpp (resp. B.def.hpp and B.inl.hpp)
Of course, all headers need to be self sufficient, and protected by header guards
The naive user will include A.hpp and/or B.hpp, thus ignoring the whole mess.
And having that organization means the library writer can solve the circular dependencies between A and B while keeping both classes in separate files, easy to navigate once you understand the scheme.
Please note that it was an edge case (two templates knowing each other). I expect most code to not need that trick.
We do that at work, its just easier to find stuff if the class and files have the same name. As for performance, you really shouldn't have 5000 classes in a single project. If you do, some refactoring might be in order.
That said, there are instances when we have multiple classes in one file. And that is when it's just a private helper class for the main class of the file.
+1 for separation. I just came onto a project where some classes are in files with a different name, or lumped in with another class, and it is impossible to find these in a quick and efficient manner. You can throw more resources at a build - you can't make up lost programmer time because (s)he can't find the right file to edit.
In addition to simply being "clearer", separating classes into separate files makes it easier for multiple developers not to step on each others toes. There will be less merging when it comes time to commit changes to your version control tool.
Most places where I have worked have followed this practice. I've actually written coding standards for BAE (Aust.) along with the reasons why instead of just carving something in stone with no real justification.
Concerning your question about source files, it's not so much time to compile but more an issue of being able to find the relevant code snippet in the first place. Not everyone is using an IDE. And knowing that you just look for MyClass.h and MyClass.cpp really saves time compared to running "grep MyClass *.(h|cpp)" over a bunch of files and then filtering out the #include MyClass.h statements...
Mind you there are work-arounds for the impact of large numbers of source files on compile times. See Large Scale C++ Software Design by John Lakos for an interesting discussion.
You might also like to read Code Complete by Steve McConnell for an excellent chapter on coding guidelines. Actualy, this book is a great read that I keep coming back to regularly.
N.B. You need the first edition of Code Complete that is easily available online for a copy. The interesting section on coding and naming guidelines didn't make it into Code Complete 2.
It's common practice to do this, especially to be able to include .h in the files that need it. Of course the performance is affected but try not to think about this problem until it arises :).
It's better to start with the files separated and after that try to merge the .h's that are commonly used together to improve performance if you really need to. It all comes down to dependencies between files and this is very specific to each project.
The best practice, as others have said, is to place each class in its own translation unit from a code maintenance and understandability perspective. However on large scale systems this is sometimes not advisable - see the section entitled "Make Those Source Files Bigger" in this article by Bruce Dawson for a discussion of the tradeoffs.
The same rule applies here, but it notes a few exceptions where it is allowed Like so:
Inheritance trees
Classes that are only used within a very limited scope
Some Utilities are simply placed in a general 'utils.h'
It is very helpful to have only have one class per file, but if you do your building via bulkbuild files which include all the individual C++ files, it makes for faster compilations since startup time is relatively large for many compilers.
I found these guidelines particularly useful when it comes to header files :
http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Header_Files
Two words: Ockham's Razor. Keep one class per file with the corresponding header in a separate file. If you do otherwise, like keeping a piece of functionality per file, then you have to create all kinds of rules about what constitutes a piece of functionality. There is much more to gain by keeping one class per file. And, even half decent tools can handle large quantities of files. Keep it simple my friend.
I'm surprised that almost everyone is in favor of having one file per class. The problem with that is that in the age of 'refactoring' one may have a hard time keeping the file and class names in synch. Everytime you change a class name, you then have to change the file name too, which means that you have to also make a change everywhere the file is included.
I personally group related classes into a single files and then give such a file a meaningful name that won't have to change even if a class name changes. Having fewer files also makes scrolling through a file tree easier.
I use Visual Studio on Windows and Eclipse CDT on Linux, and both have shortcut keys that take you straight to a class declaration, so finding a class declaration is easy and quick.
Having said that, I think once a project is completed, or its structure has 'solidified', and name changes become rare, it may make sense to have one class per file. I wish there was a tool that could extract classes and place them in distinct .h and .cpp files. But I don't see this as essential.
The choice also depends on the type of project one works on. In my opinion the issue doesn't deserve a black and white answer since either choice has pros and cons.