CODING_STYLE: mandate alphabetical include order

systemd-internal headers must not rely on include order. That means, they
either must contain forward-declarations of used types/functions, or they
must include all dependencies on their own. Therefore, there is no reason
to mandate an include order on the call-side.

However, global includes should always be ordered first. We don't want
local definitions to leak into global includes, possible changing their
behavior. Apparently, namespacing is a complex problem that people are
incapable of implementing properly..

Apart from "global before local", there is no reason to mandate a random
include order (which we happen to do right now). Instead, mandate
alphabetical ordering. The current rules do not have any benefit at all.
They neither reduce include-complexity, nor allow easy auditing of
include files. But with alphabetical ordering, we get duplicate-detection
for free, it gets *much much* easier to figure out whether a header is
already included, and it is trivial to add new headers.

diff --git a/CODING_STYLE b/CODING_STYLE
index a96ddd35980fd11aa2cf81edfee01f77d1f1a496..f13f9becbc0839d246ebffa44c34bcfee6963f72 100644 (file)
--- a/CODING_STYLE
+++ b/CODING_STYLE
@@ -295,25 +295,15 @@
   EXIT_FAILURE and EXIT_SUCCESS as defined by libc.
 
 - The order in which header files are included doesn't matter too
-  much. However, please try to include the headers of external
-  libraries first (these are all headers enclosed in <>), followed by
-  the headers of our own public headers (these are all headers
-  starting with "sd-"), internal utility libraries from src/shared/,
-  followed by the headers of the specific component. Or in other
-  words:
-
-          #include <stdio.h>
-          #include "sd-daemon.h"
-          #include "util.h"
-          #include "frobnicator.h"
-
-  Where stdio.h is a public glibc API, sd-daemon.h is a public API of
-  our own, util.h is a utility library header from src/shared, and
-  frobnicator.h is an placeholder name for any systemd component. The
-  benefit of following this ordering is that more local definitions
-  are always defined after more global ones. Thus, our local
-  definitions will never "leak" into the global header files, possibly
-  altering their effect due to #ifdeffery.
+  much. systemd-internal headers must not rely on an include order, so
+  it is safe to include them in any order possible.
+  However, to not clutter global includes, and to make sure internal
+  definitions will not affect global headers, please always include the
+  headers of external components first (these are all headers enclosed
+  in <>), followed by our own exported headers (usually everything
+  that's prefixed by "sd-"), and then followed by internal headers.
+  Furthermore, in all three groups, order all includes alphabetically
+  so duplicate includes can easily be detected.
 
 - To implement an endless loop, use "for (;;)" rather than "while
   (1)". The latter is a bit ugly anyway, since you probably really