Do stand alone C++ functions need a header file and a code file?
I am writing some C++ functions that use some of my other C++ classes but don't belong in a class themselves. They are intended to be compiled in a dll and so I was wondering if it was necessary to declare them in a separate header file or if I could/should just put the declarations in the .cc file.
Maybe this would just be bad practice?
The header file is useful because it is able to let other source files know about the functions that are declared in a different translation unit.
This is necessary by the compiler to be able to check that what you are invoking is correct for the type checker. But the necessity comes from the declaration itself not from the existence of the header file.
For a DLL, if I remember correctly, you are not forced to do it just because you are going to declare the signature of the function anyway whenever you are using them, eg.
extern C __declspec(dllimport) void foo();
Of course this means that you will need to forward declare them anyway so I don't see any problem in having an header files for your DLL, it will just keep all signatures together.
It is not strictly necessary, but it is strongly recommended.
Place the function declarations in a header file and the function definitions in a source (.cc) file. The motivation is to allow the users (here, fellow programmers) to view only the interface but not the implementation (since it can change). Moreover, it allows other source files to include your header file and use the functions provided by you.
The only exception are static functions, they should not be declared in a header file because they are not supposed to be viewed or used outside your source file..
If you are going to use a function outside of the source file in which it's defined, you absolutely need a declaration. It is best to put the declaration in a header file so that it's consistent, otherwise you just end up repeating yourself and introducing a potential source of bugs.
Related
When is it necessary to separately declare a class in a ”.h” file and provide the
function implementations in a ”.cpp” file?
It is not strictly necessary, as far as the C++ language is concerned. You can put all class methods inline in the .h file.
However, putting the implementations into a separate .cpp offers many benefits, such as:
C++ is very complex. As the code grows, it will take longer and longer to compile it. Every .cpp file that includes the same header file will end up compiling the same code, over and over again.
Related to the first point: if any change is made to the class's methods, if all the class methods are in a separate .cpp file, only that .cpp needs recompilation. If all class methods are placed inline into the .h file, every .cpp that includes will must be recompiled.
Very often, the class's methods will use other classes as part of doing whatever they need to do. So, if they're all placed inline in the .h file, the .h file that defines those other classes will need to be included also, also slowing down the compilation of every .cpp file that includes the header file. If the class methods are in a separate .cpp file, only that .cpp file needs to include the other headers, and most of the time it's only necessary to add some forward declarations to the .h.
It's done that way so that you only build the class' code one time.
If you put the class' code in the .h file, then every file that picks up the .h (to access the public functions of the class) will also duplicate the class' code.
The compiler will happily do this for you.
The linker, however, will complain mightily about duplicate lvalues in the namespace.
Along the same lines, yet conversely: inline functions need to be in the .h so that their code will get picked up in the other code files, which is exactly the intent of inline functions.
If you want to use declarations to implement/define the function, declarations that you don't want to make visible in the *.h file, then it would be necessary to move the definition of the function to a separate file.
Usually that's a good separation between class definition (.h) and class implementation (.cpp) People can just read the .h files to know and use the class without bothering reading the implementation details.
It's, however, not mandatory to always separate .h and .cpp, you can have the class definition and implementation in a single file (eg., for some simple classes, or some quick prototypes).
From a technical perspective (in terms of what a compiler needs or will accept) it is almost never necessary - it is possible to copy/paste the content of every (non-standard) header file into the source files that include them, and compile that. After all, that is effectively what the preprocessor does with #include directives - copy the included file in place, after which the resultant source is fed to later phases of the compiler.
It is possible for a compiler to run out of memory when compiling source - in which case breaking the program into smaller pieces, including header files, can help - but such circumstances (on machines with very limited hardware resources, such as memory) are very rare in modern development.
However, humans are less consistent and more error prone than compilers when dealing with source files, so humans benefit from use of header files. For example, instead of typing (or copying in) needed declarations into every source file that needs them (an activity which people find boring, and tend to make mistakes when doing) simply place the declarations in a header file and #include it when needed.
So then it comes down to when placing declarations in a header file makes life easier for a human, allowing them to avoid making errors, and to focus their effort on the creative parts of software development (implementing new things) rather than the mechanical (copying function declarations into source files that need them).
In practice, it normally works out that a class which will be used within more than one compilation unit (aka source file) is better off being defined in a header file. A class which is local to a single compilation unit (e.g. to contain implementation details for that compilation unit that do not need to be directly accessed by others) does not need to be in a header file, since it can be defined directly without use of a header. The problems come in if such "local" classes later need to be used in other compilation units - in that case, it is usually advisable to migrate the necessary declarations to a header file, to aid reuse.
Header files also tend to become necessary for authors of libraries - who write a set of functions for use by other programmers, but don't wish to ship the source. This is a non-technical constraint (i.e. policy based), rather than a technical one. In that case, they can distribute the header files and the compiled object (or library) files, and keep their source code private. Of course, technically, they could provide a set of text files with instructions of the form "copy these declarations to your program when you need to use them" instead of header files ..... but that would make the library unpopular with developers, since it forces them back into the mundane and error-prone activity of copying text around rather than doing useful development.
Considerations like reducing compile times are also non-technical reasons (a compiler doesn't care how long it takes to build a program, but people do). Separating class definitions into header (class definition, any inline functions) and separate source (definition of non-inline member functions) does tend to reduce build times, and aid with incremental builds.
Must be honest, I am getting confused between what keywords go in the function (and sometimes data member) declarations in the header file, versus what goes in the implementation file.
What is the set of rules to follow? For example
(Updated per comments)
Header files don't contain implementation except if the function is declared as "inline"
Data members don't contain a default value, unless if the type is static, const, int/enum (unless C++11)
Public/private/protected usually appear in the header file
"Static" usually appears in the header file, not the implementation file.
Are thee any other rules I can use to follow? Const?
What about for inheritance? I presume "virtual" only goes in header files? If I inherit virtual functions from Class A into Class B, does the header file of Class B have to declare the virtual functions it overrides? What about a pure virtual function in Class A, when I override in Class B would I have to include the pure virtual function definition in the header file of the derived class?
Looks like you are trying to make some formal rules without understanding how it works. But it is really simple, when preprocessor sees #include directive it just replace it with content of that file (it is like command copy whole file and paste it here). So instead of making formal rules just ask yourself questions: should this statement appear in every .cpp file that uses this header? Will they still compile? Do I really need it everywhere, or it can be in only one .cpp file that provides implementation? If answers are yes, then this statement should go to the header, if no to any of them, then put it into .cpp implementation file.
The #include statement in C and C++ is much simpler than you're giving it credit for: it takes the contents of the include'd file, and dumps it straight into your including file. This can be anything (I see a lot of newbie developers in my line of work. If it's a file on disk, at some point someone's tried to include it): even .cpp files. You can, if you want to prove it to yourself, copy & paste the contents of an included file in place of an include - everything should work as before.
For completeness: once the pre-processor has dumped all the included files to where they are asked for, the compiler compiles each file separately. This typically leaves you with a bunch of declarations with no implementation and a bunch of implementations with no declarations: the linker sorts out these references. So if you ever get a linker error, that means that somewhere you've mis-matched something: maybe you declared something twice, or never implemented it.
What we actually have is a series of best practices about what we want in header files and what we want in source files. Typically, we like to have declarations in a header file. In other words, the header file should tell me (the programmer) what things I expect to find in the implementation. Typically, these are declarations: hence why you generally only see access modifiers (public, private, protected) in headers. Some programmers will do "odd" stuff like writing constructors in header files: this is valid, but is generally not expected - you want your header to tell me what things I can use from your code, not how your code works.
This question already has answers here:
Closed 11 years ago.
Possible Duplicate:
C++ - What should go into an .h file?
I am a complete noob with C++ and slowly learning. I come from a C# background. I understand what can go into the header file versus what can go into the actual cpp implemention file. But what is the best practice for what goes where? For example, you can declare the class in the header and forward declare functions, but you can also have implementation details as inline functions.
Headers are usually reserved for your class/struct definitions, macro's and inline functions. In your CPP files you tend to have the longer implementations of your methods and member methods for your classes. Usually you only want to forward declare functions in your header that you want to allow others to use (if they do not already have an access modifier because of a class).
In general, declarations belong in the header and definitions belong in the cpp. There are some exceptions, two that I've run into are inline functions and templates. These both need to be defined in the header file with the function prototype.
There are basic two considerations here: the needs of the compiler and the goal of good source code organization. In general, I find that header files should contain as little code as possible while still keeping the compiler happy. Header files should also #include as few other header files as possible, preferring forward type declarations to #include statements whenever possible. This reduces the number of dependencies between your source files and reduces compile time. It also helps avoid circular dependencies among source files.
While almost all function implementations go in the .cpp file, template functions and inline functions need to be available to the compiler when compiling dependent types. Rather than putting these in the header file, I prefer to put them in a third file (I use the extension .icpp for 'included' implementation). This file is #included at the bottom of the header file (inside the #ifdef guard), keeping the .hpp file free from all implementation details. While not required by the compiler, the header file does contain documented declarations of all template and inline functions. Personally I never write 'implicitly' inline functions where the function definition is enclosed within the class definition.
So for all classes, types and functions that are used by more than one .cpp file, the class definitions, type definitions and function declarations go in the header file, and the corresponding function definitions (implementations) go in the .cpp file, except definitions of inline and template functions go in the .icpp file. I successfully avoid global data so I don't have any rules for that. I usually end up using static member data instead, accessed through global or static member functions, and the guidelines above apply.
Classes, types and functions that are used within one .cpp file only I sometimes put in the .cpp file. These will always be simple utility functions that have very low probability of reuse elsewhere. These go in an anonymous namespace, shielding them from name collisions with other types and functions in other .cpp files.
As to private data, conceptually the users of some class has no business knowing what private data (or functions for that matter) a class has. However, C++ syntax requires these to be declared as part of the class definition, hence they do appear in the header file. This is not usually a problem, but if it is the Pimpl design pattern can be used as a work-around. Here you define two classes, Foo and FooImpl, where FooImpl holds all your data, and Foo holds an instance of FooImpl. FooImpl.hpp is not #included in Foo.hpp, thereby hiding implementational details from the users of Foo.)
Header files commonly contain forward declarations of classes, subroutines, variables, and other identifiers.
I am working on porting some source code to a linux system, and as expected, some stuff is broken. One thing that is throwing an error for me right now, is that someone has a .h and a .cpp file that both use fclose()
The compiler is complaining about fclose() being undeclared in the header file.
here was the function declaration in the header file:
void closeFile() { if (fp) fclose(fp); }
Now, I think this is bad style, but also - how did they get this working before? Did their version of the compiler allow this kind of behavior?
Should I fix this by including stdio in the header, or move the whole thing to the cpp?
It's not bad style, you can put source code in header files, and some times you're forced to, in particular:
When defining a template class/function.
When defining an inline function.
Anyway you shouldn't put a free (defined outside a class scope) non-inline function in a header file, since that would be compiled any time a source file include such header (and this will give you a linking error).
If you're getting an error that states fclose hasn't been declared, it's probably because cstdio (or stdio.h) wasn't declared before that piece of code. Put an #include <cstdio> at the beginning of the header file.
Just to add 2 things about the other answers, remember inline is not an order, is more a guess of what the compiler should do, unless you force inline. Most compilers can decide when to inline a function, even if you did not declare it inline. It's not a must, it is a should.
Sometimes you really need to include such function/structs/classes definitions in the header, and sometimes they are not trivial or that simple. But those definitions are usually some auxiliar functions you need and you just don't want to include them on the main file, just to organize things better.
The best examples I ever seen (ok, and I didn't see those many) about this practice is game source code (that's my main interest :) ).
By the way, I usually do not put any declaration on header files (except structs and enums), I put them on separated files, unless if:
There are only a few declarations/aux functions to be made; or
These declarations are functions that I will use in another contex (of the same project, in the case) and I just think it's better to treat them as a separated 'auxiliar library' (within the same context).
Hope it helps somewhat.
Keep in mind that header files aren't compiled by themselves (usually). They are #included into source files and the definitions available when the header file is parsed are whatever was included in the source file above the header file in question.
Regardless of whether the header file is an appropriate place for the implementation of closeFile(), your header file should #include everything it needs at the top of itself. So, add #include <stdio.h> at the top of the header file.
(Note that if this is code intended to be compiled into the Linux kernel itself, you may need a different header than stdio.h. Often application-level headers aren't suitable to be used in the kernel sources.)
fclose() will be undefined if you haven't included stdio.h either in this header or before it everywhere this header is used. That is why the error occurs.
I personally see nothing wrong with the code being allowed to be in a header file, however, if it is, and you're using C99, you should declare it
inline void closeFile() { if (fp) fclose(fp); }
This means multiple compiled objects won't have closeFile() symbols (because of inline) and the inline hints to the compiler that this shouldn't be left as a function call but substituted inline which is probably want you want for speed.
The headers are included by textual substitutions (that is the whole content of the header is substituted to the #include declaration). So if there is only one .cpp file that include this particular header, this is equivalent with having the function defined in the .cpp file. I think this is the reason why it was working (at link time).
The C standard only define the header that must be included to have a function available but does not forbid the system header to include one another. So it is possible that on some system, the stdio.h header was implicitly included by another header (and thus no error reported by the compiler).
Personally, I would move such code to the .cpp file, as it will be less brittle (the header can be included by multiple .cpp files, the header will not require a previous inclusion of the stdio.h header) and will allow for quicker recompilation if the implementation must be changed (to add logging or proper error handling, as closing a file can fail).
When dividing your code up into multiple files just what exactly should go into an .h file and what should go into a .cpp file?
Header files (.h) are designed to provide the information that will be needed in multiple files. Things like class declarations, function prototypes, and enumerations typically go in header files. In a word, "definitions".
Code files (.cpp) are designed to provide the implementation information that only needs to be known in one file. In general, function bodies, and internal variables that should/will never be accessed by other modules, are what belong in .cpp files. In a word, "implementations".
The simplest question to ask yourself to determine what belongs where is "if I change this, will I have to change code in other files to make things compile again?" If the answer is "yes" it probably belongs in the header file; if the answer is "no" it probably belongs in the code file.
Fact is, in C++, this is somewhat more complicated that the C header/source organization.
What does the compiler see?
The compiler sees one big source (.cpp) file with its headers properly included. The source file is the compilation unit that will be compiled into an object file.
So, why are headers necessary?
Because one compilation unit could need information about an implementation in another compilation unit. So one can write for example the implementation of a function in one source, and write the declaration of this function in another source needing to use it.
In this case, there are two copies of the same information. Which is evil...
The solution is to share some details. While the implementation should remain in the Source, the declaration of shared symbols, like functions, or definition of structures, classes, enums, etc., could need to be shared.
Headers are used to put those shared details.
Move to the header the declarations of what need to be shared between multiple sources
Nothing more?
In C++, there are some other things that could be put in the header because, they need, too, be shared:
inline code
templates
constants (usually those you want to use inside switches...)
Move to the header EVERYTHING what need to be shared, including shared implementations
Does it then mean that there could be sources inside the headers?
Yes. In fact, there are a lot of different things that could be inside a "header" (i.e. shared between sources).
Forward declarations
declarations/definition of functions/structs/classes/templates
implementation of inline and templated code
It becomes complicated, and in some cases (circular dependencies between symbols), impossible to keep it in one header.
Headers can be broken down into three parts
This means that, in an extreme case, you could have:
a forward declaration header
a declaration/definition header
an implementation header
an implementation source
Let's imagine we have a templated MyObject. We could have:
// - - - - MyObject_forward.hpp - - - -
// This header is included by the code which need to know MyObject
// does exist, but nothing more.
template<typename T>
class MyObject ;
.
// - - - - MyObject_declaration.hpp - - - -
// This header is included by the code which need to know how
// MyObject is defined, but nothing more.
#include <MyObject_forward.hpp>
template<typename T>
class MyObject
{
public :
MyObject() ;
// Etc.
} ;
void doSomething() ;
.
// - - - - MyObject_implementation.hpp - - - -
// This header is included by the code which need to see
// the implementation of the methods/functions of MyObject,
// but nothing more.
#include <MyObject_declaration.hpp>
template<typename T>
MyObject<T>::MyObject()
{
doSomething() ;
}
// etc.
.
// - - - - MyObject_source.cpp - - - -
// This source will have implementation that does not need to
// be shared, which, for templated code, usually means nothing...
#include <MyObject_implementation.hpp>
void doSomething()
{
// etc.
} ;
// etc.
Wow!
In the "real life", it is usually less complicated. Most code will have only a simple header/source organisation, with some inlined code in the source.
But in other cases (templated objects knowing each others), I had to have for each object separate declaration and implementation headers, with an empty source including those headers just to help me see some compilation errors.
Another reason to break down headers into separate headers could be to speed up the compilation, limiting the quantity of symbols parsed to the strict necessary, and avoiding unecessary recompilation of a source who cares only for the forward declaration when an inline method implementation changed.
Conclusion
You should make your code organization both as simple as possible, and as modular as possible. Put as much as possible in the source file. Only expose in headers what needs to be shared.
But the day you'll have circular dependancies between templated objects, don't be surprised if your code organization becomes somewhat more "interesting" that the plain header/source organization...
^_^
in addition to all other answers, i will tell you what you DON'T place in a header file:
using declaration (the most common being using namespace std;) should not appear in a header file because they pollute the namespace of the source file in which it is included.
What compiles into nothing (zero binary footprint) goes into header file.
Variables do not compile into nothing, but type declarations do (coz they only describe how variables behave).
functions do not, but inline functions do (or macros), because they produce code only where called.
templates are not code, they are only a recipe for creating code. so they also go in h files.
In general, you put declarations in the header file and definitions in the implementation (.cpp) file. The exception to this is templates, where the definition must also go in the header.
This question and ones similar to it has been asked frequently on SO - see Why have header files and .cpp files in C++? and C++ Header Files, Code Separation for example.
Mainly header file contain class skeleton or declaration (does not change frequently)
and cpp file contains class implementation (changes frequently).
Header (.h)
Macros and includes needed for the interfaces (as few as possible)
The declaration of the functions and classes
Documentation of the interface
Declaration of inline functions/methods, if any
extern to global variables (if any)
Body (.cpp)
Rest of macros and includes
Include the header of the module
Definition of functions and methods
Global variables (if any)
As a rule of thumb, you put the "shared" part of the module on the .h (the part that other modules needs to be able to see) and the "not shared" part on the .cpp
PD: Yes, I've included global variables. I've used them some times and it's important not to define them on the headers, or you'll get a lot of modules, each defining its own variable.
Your class and function declarations plus the documentation, and the definitions for inline functions/methods (although some prefer to put them in separate .inl files).
the header file (.h) should be for declarations of classes, structs and its methods, prototypes, etc. The implementation of those objects are made in cpp.
in .h
class Foo {
int j;
Foo();
Foo(int)
void DoSomething();
}
I'd expect to see:
declarations
comments
definitions marked inline
templates
the really answer though is what not to put in:
definitons (can lead to things being multiply defined)
using declarations/directives (forces them on anyone including your header, can cause nameclashes)
The header Defines something but doesn't tell anything about the implementation. ( Excluding Templates in this "metafore".
With that said, you need to divide "definitions" into sub-groups, there are, in this case, two types of definitions.
You define the "layout" of your strucutre, telling only as much as is needed by the surrounding usage groups.
The definitions of a variable, function and a class.
Now, I am of course talking about the first subgroup.
The header is there to define the layout of your structure in order to help the rest of the software use the implementation. You might want to see it as an "abstraction" of your implementation, which is vaughly said but, I think it suits quite well in this case.
As previous posters have said and shown you declare private and public usage areas and their headers, this also includes private and public variables. Now, I don't want to go into design of the code here but, you might want to consider what you put in your headers, since that is the Layer between the end user and the implementation.
Header files - shouldn't change during development too often -> you should think, and write them at once (in ideal case)
Source files - changes during implementation