code-quality-analysis

Code Quality Analysis Protocol

EXTREMELY_IMPORTANT: This is a MANDATORY protocol, not a suggestion. Follow every step. Do not skip steps. Do not combine steps. Do not summarize. Work through each gate in order.

Tests verify that code WORKS. This protocol verifies that code is WELL-DESIGNED. Run these checks on any significant code you write or review.

THE 15 CHECKS

Work through each. Mark PASS, FAIL, or N/A. Do not skip any applicable check.

Readability

1. NAMING — Does every variable, function, and class name reveal its intent?

• processData() → FAIL. extractValidEmails() → PASS.
• Booleans read as questions: isValid, hasPermission, canExecute.
• No abbreviations a new reader couldn't understand.

2. FUNCTION SIZE — Does every function do exactly one thing?

• Length is the smell: past ~20 lines a function has usually accreted a second job. Extract methods. (A long but irreducible unit — e.g. a flat dispatch table — can pass.)
• Can you describe what the function does without the word "and"?

3. NESTING DEPTH — Is anything nested deeper than 2 levels?

• Every nesting level is a condition the reader must hold in their head at once. Flatten with guard clauses. Return early for invalid cases.
• Happy path should be at indent level 1.

Structure

4. SINGLE RESPONSIBILITY — Does each module/class have exactly one reason to change?

• Can you describe it in one sentence without "and"?
• If it handles both parsing AND validation AND storage, split it.

5. COUPLING — Can you change module A without touching module B?

• Count the imports. More imports = more coupling.
• Are there method chains longer than 2 dots? Each extra dot couples this code to another object's internals (Law of Demeter).

6. COHESION — Is everything inside this module related to the same concern?

• Would removing any function make the module incomplete?
• Would any function be more at home in a different module?

Safety

7. FAIL FAST — Do errors surface immediately with clear messages?

• No empty catch blocks.
• No silently defaulting to zero/null/empty on bad input.
• Errors include context: what input, what state, what was expected.