# GENERATED by `sherd slice` from vendor/principles/*.md -- do not edit.
Weigh second- and third-order consequences, not just first-order. The
immediately pleasant first-order choice is often the wrong one once
downstream effects are counted.
High-level modules should not depend on low-level modules. Both should
depend on abstractions. Abstractions should not depend on details;
details should depend on abstractions.
Do not repeat yourself. Every piece of knowledge -- logic, constant,
structure, validation rule -- must have a single, authoritative source.
When the same idea appears in two places, one will inevitably drift.
No client should be forced to depend on methods it does not use. Split
large interfaces into smaller, role-specific ones so that implementers
and consumers see only what they need.
Keep solutions as simple as possible while fully satisfying the
requirements. Prefer the design with fewer moving parts, abstractions,
dependencies, and special cases when multiple designs are equally correct.
Subtypes must be substitutable for their base types without altering
the correctness of the program. If S is a subtype of T, then objects of
type T may be replaced with objects of type S without breaking any
property that callers depend on.
Look for a well-maintained open-source solution before creating a custom
implementation. Prefer a proven fit over rebuilding an existing capability.
Software entities should be open for extension but closed for
modification. Add new behavior by writing new code, not by changing
existing, tested code.
Also called the Principle of Least Surprise (POLS). Every interface --
function signature, API endpoint, CLI flag, config option, class method,
return value -- should behave the way its user
would reasonably expect given its name, context, and the conventions of
the surrounding system. When two interpretations are possible, choose
the one that surprises fewer people.
Embrace reality and deal with it. Base every decision on how things
actually are -- the real state of the code, CI, logs, and telemetry --
not on how we wish or assume them to be. A hyperrealist reads the
machine's true signals before acting.
Diagnose problems to their root cause before designing a fix. A symptom
patched leaves the disease; find the deepest "why" first, then fix THAT.
A module, class, or function should have one and only one reason to
change. Each unit of code is accountable to exactly one actor or
stakeholder concern.
Radical truth. Be honest about problems, mistakes, and weaknesses -- do
not hide, minimize, or spin a failure. You cannot fix what you will not
name.