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.

Core Principle

Code is read far more often than it is written — optimize for the reader. The read-to-write ratio is well over 10:1, so every naming choice, function boundary, and formatting decision either adds clarity or adds cost. Clean code reads like well-written prose: names reveal intent, functions tell a story one step at a time, and the Boy Scout Rule applies — always leave the code cleaner than you found it.

Scoring

Goal: 10/10. Rate any code 0-10 against the principles below. Report the current score and the 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 may lack edge cases
• 5-6: Mixed — good patterns alongside unclear names, duplicated logic, or inconsistent error handling
• 3-4: Long multi-purpose functions, misleading names, poor or missing tests
• 1-2: Nearly unreadable — magic numbers, cryptic abbreviations, no structure, no tests

The Clean Code Framework