[asterisk-dev] header inclusion policy ?

[Luigi Rizzo]

this needs to go into the CODING-GUIDELINES once a decision is made.

What is the desired policy for header file inclusion (both system
headers and generic asterisk headers) ?

I just hit another compile error on a platform
because of missing headers in one of the apps.
I can put a bandaid in the code to fix it, but it would
be nice if we could decide for a strategy and mention it
in the coding guidelines, so future fixes will be driven
towards a given goal and not driven by random or confliction
strategies.

The commonly used (I mean, the sound ones) approaches in this area
are (A) and (B) as described below.

While i am neutral on which one we follow (and e.g. my platform of
choice, FreeBSD, uses (B) and so i am a bit more used to that), I
don't think we have the programmer resources to pick anything
different from (A).

comments welcome


A) make use of nested includes.
   In this case there is one large "compat.h"
   header which in turn includes the most commonly required
   system- and application-specific headers, possibly with OS-specific
   conditional sections.  Then the specific needs of the various
   modules are handled in individual files with a handful of
   application specific includes (e.g. tdd.h will be included in
   the 2-3 files in need of it).

B) deprecate nested includes.
   In this case each source file will include the bare minimum
   of (system and application) header files needed for its
   operation, and application specific header files WILL NOT
   have nested includes but will depend on the external C
   source to do the right thing.
   Only for portability issues you may have one "compat.h"
   file where you do conditional include of
   system headers etc. to adapt to the various platforms.

Approach A) minimizes the effort for the programmer, who
does not have to repeat the same code multiple times,
at the price of a bit of a namespace pollution and
slightly increased compilation times (because you
typically include more than what is strictly necessary).

Approach B) requires a lot (really A LOT!) more effort
on the programmer to be done properly,
and leads to some replication of source code
(i.e. the common lists of include files in different sources).
In exchance, the compile time is slightly optimized,
and you get a slightly better chanche to catch errors during
the compile phase due to a reduction in the number of symbols
declared.

As i said before, i have no direct preference from one or
the other strategy, although reasoning on the pros and cons
in the context of asterisk (also considering the manpower
behind it) leads me to think that the only obvious choice is (A).

However, right now we are taking the disadvantages from both
solution - many files include a large set of system
headers (not all necessary), and application headers
(not all necessary), so this is approach (B) without the
optimization; and even more files rely on nested includes
from asterisk headers (so its approach (A) without the
design).

	cheers
	luigi