What belongs in a header file

5/11/2011 7:48 PM EDT

In general good advice, but a few holes IMHO.

"DO create one .h header file for each "module" of the system" No. Headers should define interfaces. Sometimes one module will have many interfaces. Sometimes one interface is shared by many modules.

Headers are also often a good way to define system configurations etc, which have no relationship to modules.


"DO include in the header file all of the function prototypes for the public interface of the module it describes" No. Split up headers according to logical interfaces. Often a module has multiple interfaces and needs multiple headers. Test interfaces should be separated form "normal usage" interfaces.

"That is to say there should be no "struct { … } foo;" code in any header file." Except of course when the structure is part of the interface. For example, If you have an interface to a GPS receiver or whatever that gives current position, then "current position" is probably a struct

Structures are also useful in interfaces for setting up function pointer tables and other useful abstractions.

5/12/2011 7:45 AM EDT

Good tip about omitting the details of data structures in header files. Made me realize that I've been doing that for no good reason.

5/12/2011 10:46 AM EDT

I think that it's much better to have one header file for each module, it is less confusing. Some people that want to do "object oriented" programming in C, likes to have multiple .c and .h files for each module, this is so confusing, hard to understand and hard to mantain.

5/12/2011 2:09 PM EDT

One situation that was hard to solve involved a single code base that covered over 30 products, using 3 CPU's (x86, AVR and Arm), at least 4 FPGA implementations, and many other hardware quirks including different peripheral bus implementations. Of course, the hardware guys simply mixed-n-matched like tinker toys, to give a zillion possible combinations for the new products.

For this I ended up with (1) a compile-time constant that defined the system, and (2) a special header file that then selected the appropriate sub-header-files according to the constant. The single header was included in most (but amazingly not all) modules. This is a cross between Frankenstein and a twisty maze of little passages.

This worked only because I used the Understand editor from www.scitools.com. This editor interprets the header files and allows direct jumping (sort of hyperlinking) to declarations and references.

5/12/2011 3:09 PM EDT

I am confused by the statement "If you do have a type you need to pass in and out of your module, so client modules can create instances of it, you can simply "typedef struct foo moduleb_type" in the header file. Client modules should never know, and this way cannot know, the internal format of the struct."

If the compiler doesn't know the internals of the structure, how can it create an instance of it. I can see how the compiler could create a pointer to the moduleb_type. Is that what you mean by "creating an instance of it"?

5/12/2011 3:30 PM EDT

What is the general feeling about header files including other header files. Personally, I don't do it but I have worked with others that think that it is quite OK.

5/13/2011 4:12 AM EDT

I agree with most of this article, but I think it goes a bit far with the "hide everything" aim. It is a worthy idea, but the unfortunate reality is that C (and C++) will not let you hide data and details without a cost.

We are talking about embedded programming here - wasted code space costs money, and wasted run time costs power.

And while layers of abstraction and data hiding help code quality and testing in some ways, they detract in other ways - they can make debugging much harder, and it can be difficult to follow the flow of information.

It is common to slavishly follow the ideas that "all global data is bad", and that implementation details must be hidden at all times. The reality is that global data is sometimes the clearest and most efficient way to pass data around. And implementation details end up in header files if you want your code to be efficient. The simple answer here is to use comments or sectioning of the header file to make usage clear.

5/13/2011 4:22 AM EDT

"DON'T expose the internal format of any module-specific data structure passed to or returned from one or more of the module's interface"

I believe that rule only works if your coding standards don’t prohibit the use of malloc() or you think malloc() is a bad idea.

I would like to suggest an alternative rule:

DO run a static analysis followed by a compile of all the code if any change is made to a header file.

Terry

5/13/2011 1:42 PM EDT

Please give us the same article for C++ header files with C++ details!

5/13/2011 5:25 PM EDT

As a newcomer I think this article is of great advice. I imagine a system described in block diagrams and that each block will have a header file. However, a point made by one of the readers is good too. Header files which relate to the different interfaces seem reasonable. I think we can have one single header file as long as the different interfaces or modules are well identified inside it.

5/16/2011 5:01 AM EDT

Another thing that probably should be mentioned: try to avoid using the same name to define data types in different header files, because there is no cross-check that they are used consistently or kept separate. For example, if one module gets a definition of a structure called S from one header file (directly or indirectly), and another module gets a definition of S from another file, and they do not happen to be structurally identical (e.g. one has an int where the other has a char), then if a function in one module passes an S or a pointer to an S to a function in the other module, you are likely to get a machine-specific and unpredictable bug that will manifest itself at some time in the future.

There is nothing in C itself to prevent this from happening. It's an example of the inadequacy of a module system that works simply by pasting source files together. In a small project you can generally avoid it with some care. It's more likely to occur in a larger project with many contributors.

5/16/2011 8:19 AM EDT

“The use of abstract interfaces (and pointers) does not necessitate the use of malloc(). For example consider an abstract interface to code for one or more serial ports. The port structures can be static in the implementing code. The actual private port data does not need to be exposed and can be identified via a pointer or even a port number.”

What you say is true but if you accept that hiding the internal workings of a module is a good thing then using the port number will be better than using the pointer.

If you accept the use of malloc() is a bad thing and you are not going to use it either through choose or because your coding standards disallowed it then I don’t believe you can use the last rule.

Terry

5/16/2011 8:33 AM EDT

“Another thing that probably should be mentioned: try to avoid using the same name to define data types in different header files, because there is no cross-check that they are used consistently or kept separate. “

This should be picked up by your static checker. If you are not using one try splint which is free. I used it to get the following:

Run the command:

splint *.c

This gives the following output:

Splint 3.0.1.6 --- 11 Feb 2002

tmp2.h(9,3): Structure DUPLICATED_S redeclared with fields { int a; int b; },
previously declared with fields { char a; char b; }
A struct, union or enum type is redefined with inconsistent fields or
members. (Use -matchfields to inhibit warning)
tmp1.h(9,3): Previous declaration of DUPLICATED_S
tmp2.h(6,9): Field a redeclared as char, previously declared as int
tmp1.h(6,11): Previous declaration of a

Finished checking --- 1 code warning

For the following source code:

/////////////////////////////////////
// file tmp1.c

#include "tmp1.h"

void func1 (DUPLICATED_S *pStruct)
{
pStruct = pStruct;
}

/////////////////////////////////////
// file tmp1.h

typedef struct {

char a;
char b;

} DUPLICATED_S;

/////////////////////////////////////
// file tmp2.c

#include "tmp2.h"

void func2 (DUPLICATED_S *pStruct)
{
pStruct = pStruct;
}

/////////////////////////////////////
// file tmp2.h

typedef struct {

int a;
int b;

} DUPLICATED_S;

5/19/2011 6:59 AM EDT

“You can expose private data via a pointer without using malloc with something like:
http://pastebin.com/R6rGHmUA”

If you run this example code through splint you will get a warning about possible NULL pointers and possible memory leaks. What I think has happened is that you have started to write your own version of malloc () and I’m quite impressed that splint has spotted this fact.

Consider the following code fragment. It uses a set of functions from a module called timer0.c to measure time and it breaks the last rule.

////////////////////////////////////////////////////////////////////////////
#include “timer0.h”

void delay (unsigned int time_in_ms)
{
TIMER0_CTRL timer;

timer0_set (&timer, time_in_ms);

do {

SetWatchDog ();

} while (timer0_expired (&timer) == false);
}
////////////////////////////////////////////////////////////////////////////

The compiler allocates the memory for the timer variable and the calling function doesn’t need to worry about NULL pointers or memory leaks.

It is true that the calling function could mess with the contents of the timer structure and it would be nice if C allowed the structure to be protected but all that is needed is a bit of discipline on the part of the programmer.

I believe this is a simple and elegant solution and any attempt to apply the last rule would make it more complicated and messy.

Terry

5/20/2011 5:53 AM EDT

“The problem with the code you show is that it has limited application and requires that the specific of TIMER0_CTRL are exposed (otherwise it cannot be allocated by the caller). This breaks modularity.”

I have to disagree with your comment that “it breaks modularity”.

The timer0.c module is used as part of an embedded project with several state machines that need to keep track of time. Each state machine module has its own private timer control structure which is passed to the timer0.c module. The timer0.c module has no knowledge of the total number of timers nor does it care.

New private timers can be added to the project using something like:

static TIMER0_CTRL my_new_timer;

Allocation of memory is done by the complier and timers can be added without affect timer0.c.

Your solution would require you to check you don’t run out of timers every time a timer is added and you might need to update timer0.c to add timers when you do run out. This breaks the modularity and reusability of timer0.c.

If you look at the “stdio.h” you will see that the FILE structure is exposed. I’m not aware of this causing any problems even though there must be billions of lines of code that use this structure.

So the last rule seems to be trying to fix a problem that doesn’t exist while possible introducing real problems.

My main objection to the last rule is that if I applied it to timer0.c I would end up with a more complicated and messy solution and that would break the most important golden rule of Engineering “Thou shall strive to produce simple and elegant designs”.

Terry

5/20/2011 1:01 PM EDT

STSARCES (Standards for Safety Related Complex Electronic Systems) Annex 7 and UL 1998 are great references to embedded coding standards and prohibit the use of heap management functions (e.g. malloc(), calloc(), free()) and instead require pre-allocated RAM regions.

My biggest peeve with "C" is when header files require others to be loaded first; it should not matter what order the header files are listed in the top of a "C" source file.

Great article.

6/2/2011 1:01 PM EDT

"DON'T expose any variable in a header file, as is too often done by way of the extern keyword."

Except that you often need a global instance of something
(eg an instance of a struct with the system's state, timer-counter, ISR flags)

7/26/2011 10:03 PM EDT

Okay Michael, now what about documentation guidelines for include files. I vote zero. Documentation in .h files is a legacy concept based upon the dissemination of the interface to other parties. I prefer all documentation in the .c file. Keep it where you need it. You don't need it in .h files, you can always write a script to extract documentation from the .c file. Engineers picking up someone else's code, don't want to open two files and have to hop back and forth.

12/20/2011 9:12 PM EST

I totally disagree with the last rule "DON'T expose the internal format of any module-specific data structure passed to or returned from one or more of the module's interface functions." This is just not a reasonable thing to do in C while maintaining the ability to statically allocate structures outside of the module and I agree with others that it amounts to a solution looking for a problem. If you REALLY WANT TO HIDE the internal data structure don't even pass the struct pointers, rather use integer handles that have to be resolved to pointers internal to the functional module. That will prevent code outside the module from being able to even copy the data without using "accessor" functions in the module.