Review and refactor code for top-down readability by reorganizing functions, grouping related helpers, and rewriting noisy comments without changing behavior.
This skill is for reviewing or refactoring code so it is easier to read in one pass. Apply it when a file feels jumpy, helpers are scattered, comments are noisy, or the overall flow is hard to follow even though the behavior is mostly correct.
The core idea is that readable code should feel like a guided flow. The highest-level purpose should appear first, supporting details should appear beneath the place they are introduced, and the remaining comments should explain non-obvious context rather than obvious syntax. Think of the file like a newspaper: the headline goes at the top, supporting detail appears below it, and smaller details appear further down.
Start with the function that best explains what the file does overall. A reader should learn the main purpose of the file by reading the first important function, not by hunting through low-level helpers.
When a high-level function calls helpers, place those helpers below it whenever practical. Let the reader move downward from intent to implementation detail.
Keep functions with the same concern near each other. Orchestration, business logic, persistence, formatting, validation, and shared utilities should naturally form clusters instead of being interleaved.
Organize code for the next reader, not only for execution. A person should be able to scan from top to bottom and progressively understand more detail without constant jumping.
Comments should explain what code alone cannot: a reason, constraint, workaround, business rule, risk, or precise future fix. If a comment only restates the code, sounds vague, or preserves stale history, remove or rewrite it.
Comments should read cleanly in an editor, diff, terminal, or copied snippet. Avoid HTML, decorative markup, and formatting tricks that add clutter.
Start with the function that best explains what the code does overall. That top function is the headline. A reader should understand the file's purpose by reading it first.
When a top-level function calls helpers, define those helpers below it whenever practical.
This creates a natural downward reading flow:
A reader should be able to move downward through the file and progressively learn more detail. Avoid forcing the reader to jump around the file to understand a simple flow.
If processUserReport() calls fetchUserData(), buildReport(), and saveReport(), those functions should usually appear below it, near that flow.
Functions that belong to the same concern should live near each other.
Examples:
A file becomes easier to scan when it naturally falls into layers:
Utilities used across multiple functions should usually live together lower in the file, instead of being scattered.
Related helpers should often share a naming pattern.
Examples:
formatDate() and formatScore()loadUser() and loadAccount()saveReport() and saveInvoice()Consistent naming helps the file self-organize.
The goal is not only that the code works. The goal is that someone can read it in order and understand it quickly.
Bad comments mumble. Avoid comments like:
not sure if it worksmight cause an issueedge caseThese create uncertainty without giving useful guidance.
If a behavior is uncertain, say exactly:
Good example:
// TODO: Add a timeout check here.
// If the server response takes longer than 5 seconds,
// the UI can freeze.
Avoid comments full of background material that does not help the next reader act.
Examples of low-value detail inside code comments:
If a one-line function already clearly says what it does, do not add a long paragraph explaining it.
Bad:
// This function uses the Base64 encoding standard defined in RFC 4648...
function encodeImage(data) {
return Buffer.from(data).toString('base64');
}
Better:
function encodeImage(data) {
return Buffer.from(data).toString('base64');
}
If the comment adds no critical context, delete it.
Useful comments usually explain one of these:
If a comment mostly says what happened years ago, who wrote it, or how an older version worked, it is probably noise in the codebase.
Move history to:
Do not fill code comments with HTML or presentation markup.
Comments should be readable directly in the editor.
Avoid comments like:
// <p>Calculates the <b>final price</b> for the cart items.</p>
// <ul><li>Applies seasonal discounts</li></ul>
Prefer plain text:
// Calculates the final price for cart items.
// Applies seasonal discounts and region-based tax.
A comment should still be readable in:
Plain language beats formatting tricks.
Every comment should earn its place. If removing a comment makes the code cleaner and loses nothing important, remove it.
When applying this skill to a file, use this workflow.
Identify the function that best expresses the file's main job. Move it near the top if needed.
Read the main function and list the helpers it calls. Check whether those helpers appear below it in a sensible order.
Reorganize helpers into logical clusters, such as:
For each comment, ask:
A new reader should be able to:
might fail or weird edge case create noise without direction.