Question

If you code in C and configure your compiler to insist that all functions are declared before they are used (or if you code in C++), then you can end up with one of (at least) two organizations for your source files.

Either:

• Headers
• Forward declarations of (static) functions in this file
• External functions (primary entry points)
• Static – non-public – functions

Or:

• Headers
• Static – non-public – functions
• External functions (primary entry points)

I recognize that in C++, the term ‘static’ is not preferred, but I’m primarily a C programmer and the equivalent concept exists in C++, namely functions in an anonymous namespace within the file.

Question:

• Which organization do you use, and why do you prefer it?

For reference, my own code uses the second format so that the static functions are defined before they are used, so that there is no need to both declare them and define them, which saves on having the information about the function interfaces written out twice – which, in turn, reduces (marginally) the overhead when an internal interface needs to change. The downside to that is that the first functions defined in the file are the lowest-level routines – the ones that are called by functions defined later in the file – so rather than having the most important code at the top, it is nearer the bottom of the file. How much does it matter to you?

I assume that all externally accessible functions are declared in headers, and that this form of repetition is necessary – I don’t think that should be controversial.

Answer 1

In C code I use a simple rule:

• Every C file with non-static members will have a corresponding header file defining those members.

This has worked really well for me in the past – makes it easy enough to find the definition of a function because it’s in the same-named .h file if I need to look it up. It also works well with doxygen (my preferred tool) because all the cruft is kept in the header where I don’t spend most of my time – the C file is full of code.

For static members in a file I insist in ordering the declarations in such a way that they are defined by instantiation before use anyway. And, I avoid circular dependency in function calls almost all of the time.

For C++ code I tried the following:

• All code defined in the header file. Use #pragma interface/#pragma implementation to inform the compiler of that; kind of the same way templates put all the code in the header.

That’s worked really well for me in C++. It means you end up with HUGE header files which can increase compile time in some cases. You also end up with a C++ body file where you simply include the header and compile. You can instantiate your static member variables here. It also became a nightmare because it was far too easy to change your method params and break your code.

I moved to

• Header file with doxygen comments (except for templates, where code must be included in the header) and full body file, except for short methods which I know I’d prefer be inlined when used.

Separating out implementation from definition has the distinct plus that it’s harder to change your method/function signatures so you’re less likely to do it and break things. It also means that I can have huge doxygen blocks in the header file documenting how things work and work in the code relatively interruption free except for useful comments like ‘declare a variable called i’ (tongue in cheek).

Ada forces the convention and the file naming scheme on you. Most dynamic languages like Ruby, Python, etc don’t generally care where/if you declare things.