Modular programming guide

Penned on the 2nd day of August, 2020. It was a Sunday.

Constituting a module

In ANSI C projects, a module can be constituted in a few ways:

1. a lone header file
2. a code file and a header of the same name
3. either of the first two, but with an additional header for public-private API distinction

The module may also be coupled with a corresponding documentation file. This is covered in ADP 1 and ADP 2.

Three types of modules

Every module comes in one, and only one, of three kinds: logic module, state module, or definition module.

Logic modules can only declare and/or implement pure functions; they may not carry or modify any state whatsoever. This includes modifying state passed in through variable pointers. For any given shallow input, the output must be the same.

State modules have the sole job of managing state. They offer facilities for managing program state, an arduous task that deserves special attention. They should not offer significant logic facilities for the data they manage.

Definition modules contain neither state nor logic per se, but rather just enums, structs, typedefs and #defines used by the program. They are kept separate due to their brevity and difference from the other two kinds of modules.

Practising modular

It is good practise to put a comment at the top of each file, below the boilerplate, denoting what kind of module it is.

References & additional reading

1. Alexander Nicholi. “ADP 1.” Project repository filesystem schema. <https://aquefir.co/adp1>
2. Alexander Nicholi. “ADP 2.” Slick documentation format. <https://aquefir.co/adp2>