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 inside the accepted outcome and governing boundaries 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

Function Design

Parameter Management

• Group related positional parameters into an object, struct, or dictionary when call-site clarity or coordinated evolution requires it. Retain positional parameters when their order is conventional and the call remains clear, or an external/public signature requires them
• Preserve external/public signatures unless their migration is part of the accepted outcome or governing artifact

Single Responsibility

• Each function should do one thing well
• Extract a function when independently changing responsibilities or obscured control flow make the current unit harder to understand, verify, or reuse; retain a cohesive domain flow when extraction would create artificial coupling
• Extract complex logic into separate, well-named functions
• Functions should have a single level of abstraction