[Swan-dev] style discussion: structure of .c files
D. Hugh Redelmeier
hugh at mimosa.com
Sun Apr 22 21:40:31 UTC 2018
This is meant as a conversation starter. Thoughts?
0. First line: a succinct description of the file
1. License bumpf
2. any things mandated by standards to be first
#define _POSIX_C_SOURCE 199506L
3. #includes for headers supplied by the system.
Don't include system headers that are included by baseline header.
Generally these can be in any order so put them in a nice order.
Some OS-specific headers have ordering constraints.
By including these system headers before our project
headers, we reduce the chance of interference
4. #include the appropriate baseline header
5. #include any additional project headers
6. the rest of the file in a nice order
An exception can always be made where it makes things simpler or clearer.
Examples: A chunk of code is conditionally compiled, and a header file
is only needed for that chunk of code, it makes sense to put the
#include within that conditional.
What should be in the baseline header? Definitions that are pervasive
through the code for which the baseline applies.
- stddef.h, stdint.h, inttypes.h, stdbool.h, stdlib.h?, string.h,
- IETF-defined constants
- project-pervasive declarations (some of our library routines)
There may well have to be different baseline headers for different
- kernel code and code that interfaces with it (they need to share
- userland library code (i.e. the portable code that Henry design).
It is designed to not depend on anything about libreswan.
- userland library code that knows something about libreswan but isn't
only used inside pluto. This is tricky because it shares some
interfaces (logging) but not all with pluto. Several different
programs can use it
- pluto code
- userland code that has a close relationship with pluto (whack)
- userland non-pluto programs
include/lswtools.h? Maybe not.
Some existing project headers that perhaps should be available pervasively:
For system headers: #include <>
For project headers: #inlcude ""
As much as is reasonable, every .c file that exports some definitions
must have a corresponding .h file (with the same basename) that
declares those definitions.
More information about the Swan-dev