Principles

Browse the canonical engineering catalogue as a human-readable reference. The YAML entries remain the source of truth; these pages are generated views.

Filter 72 principles 72 entries

Simplicity, Scope, and Code Clarity

Avoid Accidental ComplexityMinimize complexity introduced by implementation choices rather than the problem itself.principleExplicit Is Better Than ImplicitMake important dependencies, state changes, defaults, and control flow visible.heuristicKISSPrefer the simplest design that correctly satisfies verified requirements.heuristicMake It Work, Make It Right, Make It FastSequence development through correctness, design quality, and measured optimization.process-modelMeaningful NamesUse names that communicate domain meaning, role, and units.heuristicNo MagicAvoid unexplained values, hidden side effects, and non-obvious conventions.heuristicPrinciple of Least AstonishmentDesign behavior and interfaces to match reasonable user expectations.principleSelf-Documenting CodeExpress intent through structure, names, types, and explicit control flow.heuristicSingle Level of AbstractionKeep a function or section focused on one primary conceptual level.heuristicSmall FunctionsPrefer functions that represent one coherent operation and can be understood locally.heuristicWorse Is BetterA simpler, sufficiently correct design can achieve wider adoption and evolve more effectively than a theoretically perfect one.design-philosophyYAGNIAvoid implementing capabilities that are not required by current evidence.heuristic

Abstraction, Reuse, and Changeability

Avoid Premature GeneralizationDelay general-purpose abstractions until commonality and variation are understood.heuristicCommon Closure PrincipleGroup elements that change for the same reasons and at the same times.principleCommon Reuse PrincipleGroup reusable elements so consumers do not depend on things they do not use.principleDRYAvoid duplicating authoritative knowledge, policy, and decisions.principleOpen/Closed PrincipleAllow known variation through stable extension points without repeatedly editing stable policy.principleSingle Source of TruthGive each authoritative fact or policy one canonical owner.principle

Modularity, Object Design, and Locality

Composition over InheritancePrefer assembling behavior from collaborators over deep implementation inheritance.heuristicEncapsulationControl access to state and preserve invariants through a deliberate interface.principleHigh Cohesion, Low CouplingKeep related behavior together while minimizing knowledge between modules.principleInformation HidingHide volatile design decisions behind stable boundaries.principleInterface Segregation PrinciplePrefer focused consumer-oriented contracts over broad interfaces.principleLaw of DemeterLimit knowledge of distant object structure and collaboration chains.heuristicLiskov Substitution PrincipleSubtypes must preserve the behavioral contract expected of the base abstraction.principleLocality of BehaviourPlace behavior near the data, UI, or concept it primarily affects.principlePackage by FeatureOrganize top-level code around capabilities or business features rather than only technical layers.organizational-principleSeparation of ConcernsSeparate responsibilities that represent different concerns or change drivers.principleSingle Responsibility PrincipleGive a module one cohesive responsibility or primary reason to change.principleTell, Don’t AskAsk behavior-owning objects to perform operations instead of extracting state and deciding externally.heuristic

Contracts, Errors, Validation, and Security

Defensive ProgrammingAnticipate invalid input, partial failure, and misuse at relevant boundaries.techniqueDesign by ContractSpecify preconditions, postconditions, and invariants for operations and types.methodFail FastDetect and report invalid conditions close to their source.principleMake Illegal States UnrepresentableUse types and constructors that prevent invalid combinations where practical.principleParse, Don’t ValidateTransform untrusted input into types that represent validated meaning.principlePostel’s Law / Robustness PrincipleHistorically: be conservative in output and liberal in accepted input; modern use requires caution.heuristicPrinciple of Least PrivilegeGrant only the permissions and capabilities required for the task.security-principle

Architecture and Dependency Direction

Acyclic Dependencies PrincipleKeep component dependency graphs free of cycles at meaningful architectural boundaries.principleClean Architecture Dependency RuleSource-code dependencies should point toward higher-level policy.architecture-ruleDependency InjectionSupply collaborators from outside a component instead of constructing hidden dependencies internally.techniqueDependency Inversion PrincipleHigh-level policy should not depend directly on volatile low-level details.principleInversion of ControlDelegate control of lifecycle or flow to a framework, runtime, or coordinating component.architecture-patternPorts and AdaptersPlace application policy behind explicit ports and implement external interactions through adapters.architecture-styleStable Dependencies PrincipleDependencies should generally point toward components that change less often.principle

State, Side Effects, Data, and Distribution

Command Query Responsibility SegregationUse different models or paths for reads and writes when their requirements materially diverge.architecture-patternCommand–Query SeparationAn operation should either change state or return information, with exceptions made explicit.principleEventual ConsistencyReplicated or derived state may be temporarily inconsistent but converges under defined conditions.system-propertyIdempotencyRepeated execution of the same operation has the same intended effect as one execution.system-propertyImmutabilityPrefer values that do not change after construction where this reduces reasoning and concurrency risk.design-property

Public APIs, Compatibility, and Evolution

Backward CompatibilityPreserve existing consumer behavior across compatible releases.evolution-principleHyrum’s LawWith enough users, every observable behavior will be depended on by somebody.lawSemantic VersioningCommunicate compatibility impact through major, minor, and patch versions.versioning-method

Testing and Verification

Arrange–Act–AssertStructure a test around preparation, one primary action, and verification.testing-patternFIRST TestsTests should be fast, independent, repeatable, self-verifying, and timely.umbrella-conceptGiven–When–ThenDescribe behavior through context, event, and outcome.testing-patternOne Logical Behaviour per TestKeep each test focused on one coherent behavior, allowing multiple related assertions.testing-heuristicRed–Green–RefactorCreate a failing test, make it pass minimally, then improve structure while preserving behavior.development-cycleTest Behaviour, Not ImplementationPrefer assertions on observable contracts over private structure.testing-principleTest PyramidUse many fast focused tests, fewer integration tests, and a small number of broad end-to-end tests as a starting heuristic.testing-strategyTest-Driven DevelopmentUse tests to drive small design and implementation increments.development-method

Performance and Resource Efficiency

Avoid Premature OptimizationDo not add complexity for unmeasured or irrelevant performance gains.heuristicMeasure, Don’t GuessBase performance decisions on representative measurement and explicit budgets.performance-principlePerformance BudgetsDefine acceptable latency, throughput, memory, and determinism limits.engineering-practice

Safe Change and Engineering Systems

Boy Scout RuleLeave the code you touch slightly better than you found it.change-principleBrooks’s LawAdding people to a late software project can make it later.lawChesterton’s FenceUnderstand why an existing rule or mechanism exists before removing it.lawConway’s LawSystem structures tend to reflect communication structures of their organizations.lawGall’s LawWorking complex systems generally evolve from working simpler systems.lawLinus’s LawWith enough qualified review, many defects become easier to identify.lawMurphy’s LawFailure paths that are possible should be expected over sufficient time and scale.law

Umbrella Concepts and Review Vocabulary

Clean CodeA broad label for readable, maintainable, intention-revealing code.umbrella-conceptSOLIDA mnemonic grouping five object-oriented design principles.umbrella-concept