name: aposd-improving-code-clarity
description: "Enforce comments-first workflow for new code and improve naming/documentation for existing code. Use when writing new classes, methods, or functions; when code is 'confusing' or 'hard to understand'; when naming precision is poor; or when variable documentation lacks units, bounds, or ownership. Triggers on: new code, comments-first, naming review, documentation review, not obvious, hard to understand. Produces well-documented code with precise naming, or identifies design problems when comments/names are hard to write."

Skill: aposd-improving-code-clarity

STOP - The Obviousness Rule

If a code reviewer says your code is not obvious, it is not obvious—regardless of how clear it seems to you. "Obvious" exists in the reader's mind, not the writer's.

For new code: Write comments BEFORE implementation. Comment difficulty signals design problems—fix the design, not the comment.

What Counts as "New Code"

Comments-first applies to ALL of these:

Comments-first ALSO applies to:
- Test methods (they're methods too)
- Lambda functions with non-trivial logic (>1 expression)
- Configuration that defines behavior
- Database migrations with business logic

Exemptions (but document why):
- One-liner utility functions with precise names: def square(x): return x * x
- Trivially obvious getters/setters with no business logic
- Character-level bug fixes (>= to >)
- Debug/logging code that will be deleted within 24 hours (mark with // TEMP:)

Comments-First Workflow

For new classes/methods, write comments BEFORE implementation:

1. Write class interface comment (what abstraction it provides)
2. Write interface comments for public methods (signatures + comments, empty bodies)
3. Iterate on comments until structure feels right
4. Write instance variable declarations with comments
5. Fill in method bodies, adding implementation comments as needed
6. New methods discovered during implementation: comment before body
7. New variables: comment at same time as declaration

Result: When code is done, comments are also done.

Why Comments-First Matters

Comment Quality Requirements

Comments must meet these criteria or they don't count:

If your comment just restates the function name, you haven't done comments-first.

Comment Types

Comment Levels

Variable Comment Checklist

For each variable, answer these questions in the comment:

• [ ] What are the units? (seconds? milliseconds? bytes?)
• [ ] Are boundaries inclusive or exclusive?
• [ ] What does null mean, if permitted?
• [ ] Who owns the resource (responsible for freeing/closing)?
• [ ] What invariants always hold?

Goal: Comment should be complete enough that readers never need to examine all usage sites.

Naming Principles

Two Required Properties

Naming Procedure

1. Name Evaluation Test:
   "If someone sees this name without declaration or context,
   how closely can they guess what it refers to?"

2. Precision Check:
   - Could this name refer to multiple things? → Too vague
   - Does this name imply narrower usage than actual? → Too specific
   - Target: name matches actual scope exactly

3. Consistency Check:
   - Is this name used everywhere for this purpose?
   - Is this name used ONLY for this purpose?
   - Do all variables with this name behave identically?

Common Naming Mistakes

Red Flags

Interface vs Implementation Comments

Anti-Rationalization Table

Classic Rationalizations

Pressure-Based Rationalizations

Technical Rationalizations

Types vs Comments

Strong type systems are valuable but don't replace comments:

Emergency Bypass Criteria

Skip comments-first ONLY when ALL of these conditions are true:

1. Production is down RIGHT NOW
2. Users are actively impacted, security breach in progress, OR data loss occurring
3. The fix is minimal (rollback or single-line change)
4. You commit to returning for documentation within 24 hours

If bypassing: Add TODO marker: // TODO(YYYY-MM-DD): document - emergency fix for [issue]

Quick Reference

BEFORE writing any new code:

1. COMMENT FIRST - Write interface comment before implementation
2. NAME PRECISELY - Can someone guess what it is in isolation?
3. NAME CONSISTENTLY - Same name everywhere, only for this purpose

WHEN commenting existing code:

1. DON'T REPEAT - Use different words than the code
2. PRECISION for variables - Units, bounds, null, ownership, invariants
3. INTUITION for methods - Intent, reasoning, what not how
4. HARD TO DESCRIBE? - Fix the design, not the comment

DESIGN SMELL SIGNALS:
- Hard to write simple comment → design problem
- Hard to pick clear name → design problem
- Interface must describe implementation → shallow abstraction

Chain