[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

   Unlikely example:
	#define _POSIX_C_SOURCE 199506L
   See
	<https://www.gnu.org/software/libc/manual/html_node/Feature-Test-Macros.html>

   Real example:
	#include <pthread.h>

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, 
  limits.h?
- IETF-defined constants
- project-pervasive declarations (some of our library routines)

There may well have to be different baseline headers for different
contexts:

- kernel code and code that interfaces with it (they need to share
  definitions)
  	linux/include/libreswan.h?

- 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:
  	linux/include/libreswan.h?
	include/constants.h
	include/puluto-constands.h
	include/chunk.h
	include/shunk.h
	include/deltatime.h
	include/monotime.h
	include/realtime.h
	include/lswalloc.h

Related conventions:

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 mailing list