Software Design

Core Principle

Build the simplest design that faithfully represents the problem's real contracts, responsibilities, and sources of variation. Optimize for a coherent, maintainable system rather than the fewest lines changed or the smallest immediate edit. An abstraction is valuable when it captures a genuine boundary; introducing layers by habit is not an improvement.

Responsibility and Change Boundaries

• One reason to change per responsibility. Group behavior by what it does and why it changes. Separate concerns that evolve independently, even if combining them is initially convenient.
• Reusable definitions versus instance data. Keep stable algorithms, policies, schemas, and instructions separate from invocation-specific values, current state, temporary observations, and environment bindings. Reusable artifacts should not silently capture a snapshot of one use.
• Entry points versus core behavior. CLI commands, notebooks, scheduled jobs, web handlers, and event handlers adapt their environment to reusable operations. Parsing, startup, and I/O orchestration should not be entangled with the processing logic they invoke.
• Information lives at its owning boundary. A value, decision, or rule belongs where its meaning is defined and its lifecycle is managed. Avoid duplicate definitions and hidden assumptions distributed across consumers.
• Dependencies are legible. Callers and maintainers should be able to identify what a component needs, which inputs vary its behavior, and who decides their values. Prefer explicit inputs at meaningful boundaries over implicit state or unrelated hardcoded choices.

Honest Contracts and Failure Behavior

• Required inputs are required. Missing configuration, invalid domain values, and violated invariants produce clear, actionable failures rather than silently becoming convenient alternatives.
• A default is a declared part of the contract, not a means of concealing an undecided value. Optionality, coercion, retry, recovery, and fallback behavior require a real semantic or operational reason.
• Model the actual allowed states. Do not make invalid input seem valid by inventing substitutions, accepting absent fields as meaningful values, or treating impossible states as routine success paths.
• Compatibility supports real consumers and deployed contracts, not every intermediate design a feature branch once contained. Before release, replace superseded names, paths, schemas, and behaviors consistently rather than preserving speculative legacy routes. Preserve compatibility when an actual published interface, persisted data, or external consumer requires it.
• Errors remain observable at the layer responsible for addressing them. Recovery is appropriate when the system has a well-defined recovery policy, not merely because execution might fail.

Explicit Choices Without Mechanical Patterns

• Parameters and injection: Caller-controlled inputs or dependencies belong at an explicit interface when they vary between invocations. Prefer required parameters when callers must decide; use defaults only for meaningful, stable choices. Do not pass every invariant through a chain of parameters or create dependency-injection machinery without a real seam.
• Named values and domain modeling: Give meaningful, recurring, or policy-bearing values a discoverable home. Constants name fixed values; Literal types constrain an allowed set; enums model related named domain choices. Choose the representation that matches the concept rather than replacing every literal indiscriminately.
• Abstractions: Extract a module, function, type, configuration layer, or shared rule when it makes ownership, reuse, change, or testing clearer. Avoid one-off indirection, unnecessary configurability, and abstraction for imagined future extensions.
• Change scope: Update affected callers, contracts, and tests when a real interface changes. Do not preserve a weak interface merely to avoid touching consumers, but do not refactor unrelated working code just for architectural tidiness.

Same Principle Across Different Surfaces

These examples illustrate change and ownership boundaries, not mandatory recipes for specific technologies.

Design Standard

A well-structured implementation makes it straightforward to answer: What is invariant? What changes, who chooses it, and where does that choice enter? Which values are valid? Who owns errors and recovery? Which consumers actually depend on the old contract?

Prefer a small number of clear, justified boundaries over both hidden coupling and speculative architecture. Where tradeoffs exist, make the chosen semantics explicit rather than hiding them in fallback logic, defaults, or incidental implementation details.