Reviewing Readability

Reviewing Readability

Review all comments, docstrings, and names (functions, classes, variables, tests) in the target code for clarity and conciseness, and flag non-obvious logic or unclear function purpose that lacks documentation.

This skill only evaluates: it produces findings with concrete proposed rewrites and does not apply them. The caller decides whether to apply the rewrites or present them as feedback.

Audience

The reader is a developer unfamiliar with the implementation context who is trying to understand the logic in the location they are currently reading. They have general Python/TypeScript expertise but don't know the history of why things were built this way.

Principles

1. Explain intent, not mechanics — don't restate what the code does; explain why or what would go wrong without it.
2. Lead with the main idea — the first sentence should state the rule or intent; put mechanics, edge cases, and exceptions after. A comment can be concise and accurate yet still bury the point by opening with the mechanics.
3. Concise wins — shorter comments are easier to understand. If a 4-line comment can be 2 lines, make it 2.
4. Use a list for multiple cases — when a comment enumerates several conditions, outcomes, or steps, a bulleted list (-) is usually easier to scan than the same content packed into prose. Lead with a one-line summary, then list the cases.
5. Avoid jargon without context — if a term is project-specific (e.g. "delta path", "fragment path", "DG"), either define it briefly or use a more descriptive phrase.
6. Names should stand alone — a test name or function name should communicate what it does without needing to read the docstring.
7. Comment non-obvious logic, not the obvious — skip comments that restate the code (# increment counter), but flag genuinely complex or non-obvious logic that has no explanatory comment. Likewise, flag a function whose purpose isn't clear from its name and signature and that lacks a brief docstring; leave self-explanatory functions undocumented.
8. Comments that say "unreachable" or "no-op" should explain why — the reader needs to know why the case can't happen or why no action is needed.
9. Prefer active voice; name the actor — passive constructions ("the id is assigned", "completions that are reported") force the reader to infer who does what. Say who acts on what ("the runner assigns a new id", "the frontend reports completions"). This is easy to miss because passive prose can still be accurate and concise — check for it explicitly.

Evaluation Process

1. Collect all comments, docstrings, class names, function/method names, and test names in the target scope.
2. For each item, ask:
   • Would a newcomer understand this on first read?
   • Is there jargon that isn't defined nearby?
   • Could it be shorter without losing meaning?
   • Does it explain the "why" or just the "what"?
   • Does the first sentence state the main idea, or does it bury it under mechanics?
   • If it enumerates several cases, would a bulleted list scan better than prose?
   • Is it in passive voice? Would naming the actor and switching to active voice read more directly?
   • For names: does it communicate the purpose without reading the body?
3. Also scan for missing documentation: is there complex or non-obvious logic with no explanatory comment, or a function whose purpose isn't clear from its signature and that has no docstring? Any comment or docstring you propose adding must itself follow the principles above — lead with the intent, stay concise, use active voice, and don't narrate the obvious.
4. Report the findings per the Output Format below.

How much to flag

Readability fixes are cheap — a comment reword or a rename takes seconds, so don't spend effort ranking findings by importance or deciding what's "worth it."