From: Bertrik Sikken <bertrik_at_sikken.nl>
Date: Mon, 28 Apr 2008 02:22:06 +0200

Hi,

Is there a policy or common understanding on "DO's and DON'Ts" for
header files in rockbox?

I'd like to propose the following:
(which I intend to be basically consistent to what is currently used)

1) use of #include <xxx.h> vs. #include "xxx.h"
Use #include <foo.h> only for "standard library" header files
(stdio.h etc.) and use #include "foo.h" for the rest

2) #include'ing header files within header files
(this one may be controversial)
Header files can include other header files. Each header file takes care
of itself to make sure it #include's exactly the stuff it needs, nothing
more, nothing less. The advantage is that if one module wants to access
another, it only has to #include the others' header file and there's no
need to hunt down additional required header files.

3) putting private constants / structures /types in header files
The header file should expose only the interface needed to use the
functions from the .c file, so internal types and constants should be in
the .c file.

4) .c file #including its own header file
The .c file should always #include the header file to make sure
that the interface in the header file and the implementation in the
.c file are consistent (the compiler will warn if they're not).

5) use of extern qualifier for function declarations
I think there's no need to do this in C, but I still see it a lot in
the rockbox code.

It's not my intention to suddenly tear up the entire codebase but
I'd like to take these guidelines into account when modifying code
anyway, although 4) is basically essential IMO.
I'd like to work on 2), especially making sure that only exactly the
needed stuff is included in header files. For example metadata.h
needs to know about struct mp3entry which is in id3.h, but it includes
playback.h instead (which in turn #include's id3.h but doesn't really
need it. In the end it all works out, but in a rather complicated way).

What do you think?

Kind regards,
Bertrik
Received on 2008-04-28