Clean Code Framework

A disciplined approach to writing code that communicates intent, minimizes surprises, and welcomes change. Apply these principles when writing new code, reviewing pull requests, refactoring legacy systems, or advising on code quality improvements.

Core Principle

Code is read far more often than it is written. Optimize for the reader. Every naming choice, function boundary, and formatting decision either adds clarity or adds cost. The ratio of time spent reading code to writing code is well over 10:1. Making code easier to read makes it easier to write, easier to debug, and easier to extend.

The foundation: Clean code is not about following rules mechanically -- it is about caring for the craft. A clean codebase reads like well-written prose: names reveal intent, functions tell a story one step at a time, and there are no surprises lurking in dark corners. The Boy Scout Rule applies: always leave the code cleaner than you found it.

Scoring

Goal: 10/10. When reviewing or writing code, rate it 0-10 based on adherence to the principles below. A 10/10 means full alignment with all guidelines; lower scores indicate gaps to address. Always provide the current score and specific improvements needed to reach 10/10.

• 9-10: Names reveal intent, functions are small and focused, error handling is consistent, tests are clean and comprehensive.
• 7-8: Mostly clean with minor naming ambiguities or a few long functions. Tests exist but may lack edge cases.
• 5-6: Mixed quality -- some good patterns alongside unclear names, duplicated logic, or inconsistent error handling.
• 3-4: Significant readability issues -- long functions doing multiple things, misleading names, poor or missing tests.
• 1-2: Code works but is nearly unreadable -- magic numbers, cryptic abbreviations, no structure, no tests.