Function declarations in a header

Question

If I am creating a header file containing the definition of several functions, why is it good practice to also include function declarations within the same header? It seems redundant to include the declarations when the definition itself will suffice.

Furthermore I'm trying to understand what the declarations are for. It seems like if the function isn't defined in the same file that the declaration is in, you can't use the declaration in another file by itself and use the function.

Is there a specific case that would serve as a good example of how it used?

Answer 1

One important aspect not mentioned by the other answers is compilation speed: Every time a function definition is seen by the compiler, it has to generate code for it, even if that code is not needed within the given translation unit and redundant, since the compiler can't know that another compilation unit will actually provide the compiled function.

Most header files are compiled two to ten times, putting an function definition into a header will slow down the compilation of that function by that same factor.

You might not find this important because your project is small, but it becomes important with large projects as it can heavily impact you change-compile-test-cycle. It is one of the big reasons why compiling a C program is much less time consuming than compiling an equivalent C++ program.

Answer 2

Typically, you would place your declarations in a header file and your definition in an implementation file. There are several reasons for this:

1) It improves readability and provides a "function list" for anyone else who might read your code.

2) If you happen to product a library, you can simply ship the header file and the library's binary without having to release your full source code.

3) If you need to make platform dependent implementations, you can have a different implementation that gets compiled for the same header.

The list can go on, but the basic reason it is done: everyone else expects it to be done.

There are a few exceptions to this rule (inline, static, and templates). In all cases, you should scope guard your header file to prevent them from being brought in multiple times.

Answer 3

If I am creating a header file containing the definition of several functions,

Stop doing that.

why is it good practice to also include function declarations within the same header?

It's not. Just put the declarations in the header, and only put the definitions in the corresponding .cpp file.

The only exception is if you're declaring a function inline (or perhaps static; or you might need to with template functions, if your compiler is broken), in which case you would put both in the header file. The reason why you have both is so that when you refer to a function defined later in the same file, you already have the declaration at the top, such that the function can be located by the compiler. If you don't do this, the compiler will choke.

Answer 4

For people reading through the header file they may find it easier to see all the declarations in one place without having to read through the implementation.

Saying that, I'm not sure it is needed to forward declare function in the same header and in template classes that I have seen (like boost::scoped_ptr) people don't bother to forward declare functions

Answer 5

It is generally bad to put a function definition into a header file since including the file into multiple sources will result in multiple definitions. It's only OK if the function is declared static or inline, or is part of a template.

You will require a separate declaration if a function is called before it is defined. Otherwise you're right, the definition will suffice by itself.