software simplicity

• variable names contain only english words
• shortened english words are allowed if unambiguous in context
• single-letter variable names are allowed in very small scopes

• if single-letter names are used:

  • i or j for indices
  • otherwise alphabetical order a, b, c, …
• avoid bindings used only once
• avoid identifiers with uppercase characters
• no operator overloading
• keep code to the essentials
• examples must run
• examples must exercise all demonstrated features

• strict call by contract
• always assume valid input
• no asserts or defensive checks outside the contract
• simplify by extending the contract, not by adding code
• defensive checks excluded by design must not exist
• omit error handling when the goal is instruction

• structure modules to match visible or logical boundaries
• keep the call hierarchy tidy
• use bottom-up accretive composition
• each component does one thing
• reduce coupling
• no hidden control flow or registries
• intermediate formats must have defined mappings
• inline when small and used at most twice
• outline when large or used more than twice

• prefer positive conditions over negated control flow
• use language truth semantics consistently
• identifiers are either value-replaceable or context-associated, not both
• preserve referential transparency where possible
• preserve idempotency where applicable
• favor falsifiable structure over implicit behavior

• do not repeat yourself
• do not implement unused or speculative functionality
• convention over configuration
• backward compatibility is irrelevant for new programs
• common non-language conventions are optional

• test minimal calls and compositions
• surface compile errors, type changes, exceptions, and segfaults
• assertions are only attached to data flow
• test code structure must not be influenced by assertions

• test fine-grained data assumptions
• depend on already-working basics
• remain separate from basic tests

• single compilation units
• include headers or c files directly for small libraries
• declare all variables at function start

• use implicit casts where correct
• avoid explicit casts unless required
• do not use ++ or --
• use explicit arithmetic
• do not rely on indentation-sensitive syntax

• do not use enums
• use 0 instead of NULL
• prefer pointer arithmetic over indexed address-taking
• avoid unused initialization or deinitialization

• define target platform and standards explicitly
• use inttypes.h
• use while(1) instead of for(;;)
• prefer caller-provided memory

• software development is managing complexity
• complexity often arises from one component doing multiple things
• contracts are a primary complexity-reduction mechanism
• separating validation from logic reduces complexity

• algorithmic identity encoding is language-independent
• purely functional descriptions are canonical
• imperative or stateful forms are projections, not inverses
• avoid hidden state and order dependence

• principle of least surprise
• avoid order-dependent behavior
• avoid implicit registries and global state

• key-value tree structures
• derivative configuration files
• defined intermediate representations

single-letter variables are acceptable when structure dominates over data. alphabetical ordering encodes minimal ordering information and reduces semantic collision.

extending a contract is a structural operation; adding defensive code is not. when invalid states are excluded by design, checks only add noise and execution cost.

basic tests act as execution sentinels. detailed tests encode semantic assumptions. separation reduces maintenance cost and supports automated refactoring.

early declaration matches actual stack allocation and provides a complete view of storage. late declaration does not correspond to runtime behavior in c.

functional representations avoid hidden mutation and order dependence, making them suitable as canonical descriptions from which other forms are derived.

external conventions not enforced by the language often add complexity without compensating expressive power.