Essential

essential.md

Essential Principles

Commonly occuring good advice aimed at improving maintainability.

Brevity

• Avoid duplication, tautology, repetition, duplication, and saying the same thing over and over in different ways.
• Everything (words, statements, comments) should have a clear purpose.

Resources

• Don't repeat yourself - Wikipedia
• Occam's razor - Wikipedia
• Chesterton's fence - Wikipedia

Complexity

• Avoid complexity.
• Encourage simplicity.

Resources

• Simple Made Easy - Rich Hickey (2011)

Coupling and Cohesion

• Avoid coupling.
• Encourage cohesion.

Examples

• Functions
• Classes
• Source files / modules
• Packages / projects
• Teams

Build Systems vs Toolchain Configuration

Many well-meaning projects store toolchain configuration in their build system description. Here's an example of a C++ project combining the concerns of configuring a specific compiler, with describing build targets. This is very common because CMake makes it easy to do. In reality, a CMakeLists.txt file should never contain a compiler flag because this couples the description of what targets to make (a build system concern) with what flags to pass when building (a toolchain concern). The result is a brittle configuration which breaks immediately when a novel toolchain is used.

Cyclic Dependencies

• Avoid cycles in your graphs.

Examples

• Recursion
• CI pipelines which are triggered by pushes, and also cause pushes (see GitLab guidelines).