coding_principles.md

Always follow these timeless principles when writing code, ordered by priority:

1. KISS (Keep It Simple, Stupid)

   • Keep the solution as simple as possible. Avoid unnecessary abstractions, premature optimization, or clever hacks.

2. Optimize for Cognitive Load

   • Code should fit in human working memory. Prioritize readability, clarity, and simplicity over cleverness.

3. Separation of Concerns

   • Ensure each module/class has a clear and distinct purpose. No mixing of unrelated responsibilities.

4. Single Responsibility Principle (SRP)

   • Each function or class must have only one reason to change.

5. Explicit Dependencies & Inversion of Control

   • Make dependencies obvious and controllable. Avoid hidden couplings and hard-coded wiring.

6. Composition Over Complex Inheritance

   • Build systems from small, interchangeable pieces instead of deep inheritance hierarchies.

7. DRY (Don’t Repeat Yourself)

   • Eliminate duplication, but only when it does not violate simplicity, SRP, or clarity.

8. YAGNI (You Aren’t Gonna Need It)

   • Do not add features, abstractions, or parameters unless they are explicitly required.

9. Fail Fast, Fail Loud

   • Validate inputs early, surface errors immediately, and avoid silent failures.

---

Rules of Engagement:

• Prioritize the higher-ranked principles over lower-ranked ones.
• Write code for humans first, machines second: clarity and maintainability matter more than micro-optimizations.