RonanCodes/coding-principles

Coding Principles

Quick reference index. Each section links to a detail file with examples — read those when a specific principle is relevant.

Simplicity

| Principle | Stance | |-----------|--------| | KISS | The simplest solution that works wins. "Clever" = hard to maintain. | | YAGNI | Don't build for hypothetical futures. Predicted requirements are usually wrong. | | No premature optimization | Make it work, make it right, make it fast — in that order. Profile before optimizing. |

See: principles/simplicity.md

Abstraction

| Principle | Stance | |-----------|--------| | Rule of Three | Don't abstract until you've seen the pattern 3 times. Two is coincidence. | | DRY | About knowledge, not code. Two identical functions can represent different knowledge — that's OK. | | Single Source of Truth | One authoritative place for each piece of data. Derive, don't duplicate. |

See: principles/abstraction.md

SOLID

| Principle | One-liner | |-----------|-----------| | Single Responsibility | One reason to change | | Open/Closed | Extend by adding code, not modifying existing code | | Liskov Substitution | Subtypes must be drop-in replacements for base types | | Interface Segregation | Many specific interfaces > one fat interface | | Dependency Inversion | Depend on abstractions, not concretions |

See: principles/solid.md

Boundaries

| Principle | Stance | |-----------|--------| | Separation of Concerns | UI, business logic, and data access are separate. Always. | | Law of Demeter | a.getB().getC().doThing() is a red flag. Only talk to immediate friends. | | Least Privilege | Functions receive only the data they need. Private by default. | | Deep Modules | Small interface, large behaviour behind it (Ousterhout). Especially important when delegating implementation to agents: a deep module lets a human review the interface contract and delegate the inside. Background: llm-wiki-ai-research:deep-modules-for-ai. | | Push reviewer, pull implementer | In multi-agent setups, push coding standards into the reviewer agent's prompt; let the implementer pull standards on demand. Background: llm-wiki-ai-research:push-vs-pull-coding-standards. |

See: principles/boundaries.md

Pragmatic Development

| Principle | Stance | |-----------|--------| | Tracer Bullets | Build a thin end-to-end slice first. Validate architecture before building features. | | Don't Outrun Your Headlights | Small steps with feedback. Feedback rate is your speed limit. | | Fail Fast | Surface errors immediately. Don't hide them, don't continue in a broken state. |

See: principles/pragmatic.md

Craftsmanship

| Principle | Stance | |-----------|--------| | Boy Scout Rule | Leave code better than you found it. Small improvements, not rewrites. | | Least Surprise | If a function name says "get", it shouldn't modify state. No hidden side effects. | | Composition over Inheritance | Prefer combining objects over class hierarchies. Inheritance is rarely the right call. |

See: principles/craftsmanship.md

Testing

| Context | TDD? | Notes | |---------|------|-------| | Backend | Mandatory | Write the test first. Business logic bugs are expensive. | | Frontend | Optional | When it adds value — complex logic, utils, critical paths. |

Backend TDD workflow: failing test → minimum code to pass → refactor → repeat.

When Principles Conflict

1. Clarity beats cleverness — when in doubt, be obvious
2. Context matters — a prototype has different needs than production
3. Principles guide, not govern — know when to break rules deliberately
4. Rule of Three before DRY — duplication is cheaper than the wrong abstraction