coding-principles

# Language-Agnostic Coding Principles ## Core Philosophy 1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) 3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits carries enough surface to justify the full convergence process first. 4. **Explicit over Implicit**: Make intentions clear through code structure and naming 5. **Delete over Comment**: Remove unused code instead of commenting it out ## Code Quality ### Continuous Improvement - Refactor related code named by the user or current task/design artifact when it reduces the change's risk or maintenance cost - Improve code structure incrementally - Keep the codebase lean and focused - Delete code proven obsolete by the requested change after checking its callers; report uncertain or out-of-scope cleanup separately ### Readability - Use meaningful, descriptive names drawn from the problem domain - Use full words in names; abbreviations are acceptable only when widely recognized in the domain - Use descriptive names; single-letter names are acceptable only for loop counters or well-known conventions (i, j, x, y) - Extract magic numbers and strings into named constants - Keep code self-documenting where possible...