The order of #include statements

Hello,

     We require that #include statements are alphabetized, with certain
exceptions. The presence of old files with out-of-order #includes makes
it difficult to enforce this policy because it is often difficult to say
whether the #includes were already 100% ordered without ordering them
first and then comparing the results -- a time consuming process.

Also, it is not clear what the alphabetical order is, exactly, when
files contain non-alphabet characters such as '.' and '_'. The "natural"
order may differ from what a sort(1) command would produce, for example.
There is also a question of case-sensitivity.

Finally, it is not clear how conditional #include statements should be
handled, especially when there are multiple #includes under a single
#ifdef condition.

I suggest that we automate this instead of doing everything manually. It
should not be very difficult:

1. #include "" goes before any #include <>.

2. do not touch the inner #include <> order. Move <> includes carefully
as they may have #ifdef protections. It is probably easier and safer to
move "" includes only. No "" includes should be included conditionally
(this will require a few code changes).

3. each src/ file, with a few hard-coded exceptions, must start with
#include "". If there is no "" to include, include "config.h". Do not
include "config.h" or "squid.h" if there is another "" include.

4. "config.h", if any, goes first. "squid.h", if any, goes first or
second, depending on whether there is "config.h"

5. Other "" includes are sorted using ascending ASCII character value
order. Small letters are capitalized for sorting purposes.

I am sure there will be a few exceptions and the above needs some
polishing, but I think we can automate this pretty well and add to the
SourceFormating scripts.

Is there a better way to enforce the #include rules? Or should we drop
the ordering rules instead?

Thank you,

Alex.
Received on Thu Oct 14 2010 - 17:10:05 MDT