software-principles

Software Development Principles Pyramid

Use this rubric whenever two or more engineering principles materially conflict.

Treat this order as the default decision hierarchy, not as a substitute for explicit requirements, security constraints, compatibility guarantees, operational needs, or measured evidence.

Earlier principles have higher priority than later ones.

---

Priority order

1. Make it work

   • Meet the current acceptance criteria correctly.
   • Satisfy all known functional, security, compatibility, reliability, operational, and explicit performance requirements.

2. YAGNI

   • Avoid speculative features, abstractions, extension points, and code paths.
   • Do not implement functionality that is not currently required.

3. Least surprise

   • Follow established language, framework, API, and project expectations.
   • Prefer behavior that another engineer would naturally expect.

4. KISS

   • Prefer the simplest design that satisfies the known requirements.
   • Reduce moving parts before introducing abstractions.

5. Consistency

   • Align with existing project conventions whenever doing so remains simple and unsurprising.
   • Do not introduce a different style unless it clearly improves the code.

6. DRY

   • Remove duplication only when the resulting abstraction is clearer than the duplicated code.
   • Keep small duplication when extracting it would create an unclear or overly generic abstraction.

7. Local clarity

   • Improve names, boundaries, readability, and local structure.
   • Avoid indirection whose only purpose is stylistic cleanliness.

8. SOLID

   • Apply specific SOLID principles only when they solve an observed responsibility, dependency, or substitution problem.
   • Do not apply SOLID mechanically.

9. Design patterns

   • Introduce patterns only for demonstrated recurring design problems.
   • Do not introduce factories, strategies, visitors, decorators, mediators, etc. solely because they are "good architecture."

10. Future extensibility

    • Prepare for future change only when there is concrete evidence it is likely.
    • A roadmap item, existing second implementation, or repeated change request is evidence.
    • Speculation is not.

11. Boy scout cleanup

    • Make small, safe, opportunistic improvements.
    • Do not mix broad refactoring with behavioral changes unless required.

12. Speculative optimization

    • Treat optimization as a hypothesis until measurement proves otherwise.
    • Optimize only after profiling or measuring a material bottleneck.
    • Explicit performance requirements belong under Make it work, not here.

---

Decision workflow

For every significant design trade-off:

1. State the current requirement and acceptance criteria.

2. Identify the principles that genuinely conflict. Do not manufacture a conflict merely because multiple principles are relevant.

3. Identify the highest-priority principle involved (the one appearing earliest in this list).

4. Choose the smallest solution that:

   • satisfies the requirement;
   • preserves that higher-priority principle;
   • introduces the least additional complexity.

5. If rejecting a lower-priority improvement:

   • explain why;
   • record the concrete trigger that would justify revisiting it later.

6. Verify the result proportionately:

   • correctness with tests;
   • optimization with measurements.

---

Practical rules

Prefer:

• a small implementation over a reusable framework for one known use case;
• explicit code over clever abstractions;
• simple duplication over premature generalization;
• existing project conventions over introducing a new style;
• composition only when it genuinely simplifies responsibilities.

Avoid introducing:

• interfaces for a single implementation;
• factories without multiple construction strategies;
• strategies without multiple algorithms;
• visitors without multiple operations;
• plugin systems without actual plugins;
• dependency injection layers solely for "future flexibility."

Keep cleanup scoped to the current task.

Treat optimization claims as hypotheses until measured.

---

What counts as "Make it work"

Some requirements are non-negotiable and belong to the top layer of the hierarchy. This hierarchy does not override them.

When the requirement explicitly demands:

• security,
• compatibility,
• latency,
• throughput,
• memory limits,
• scalability,
• fault tolerance,
• regulatory compliance,
• observability,

those requirements are part of Make it work.

Do not sacrifice them in the name of simplicity.

---

Communicating the decision

When explaining a trade-off, use this structure:

We chose [option] because it satisfies [current requirement] while preserving [highest-priority principle].

We are not applying [lower-priority principle] yet because [specific cost or missing evidence].

Revisit this decision when [concrete trigger] occurs.

---

Examples

Good

"We have one implementation today, so introducing an interface would violate YAGNI."

"There are only two similar code blocks. Extracting them would create a less clear abstraction, so we keep the duplication."

"Performance is not currently a bottleneck, so we keep the simpler implementation until profiling indicates otherwise."

Bad

"Let's introduce a Strategy pattern because we might need another implementation."

"Let's create an abstract base class for consistency."

"Let's optimize this loop because it feels inefficient."

---

Attribution

Early versions of this skill were inspired by Bartosz Krajka's The Pyramid of Software Development Principles (2019). The hierarchy and guidance here are independently curated for AI-assisted engineering and code review, and may diverge from that post as this skill evolves.