Rename for Clarity Before You Restructure

A refactoring sequence where the first pass only improves names — variables, functions, parameters — with no structural change, and only after the code reads clearly do you move or split anything.

You can't draw the right boundaries in code you don't understand, and unclear names are the main reason code is hard to understand. Renaming is a safe, mechanical change that makes purpose visible; once things are named for what they actually do, the correct structure often becomes obvious. Claude is good at proposing intention-revealing names because it can read the whole function's behaviour at once.

Before restructuring any code where the names are vague, abbreviated, or misleading — data, tmp, handle, flag2. Especially in code you didn't write.

Code that's already clearly named — skip straight to the structural change. And avoid sweeping renames in a shared branch mid-feature, where they'll create noisy conflicts for teammates.

Here is a function I want to refactor: <paste>.

First pass only: propose better names for the variables, parameters, and helpers based on what they actually do — no structural changes yet. Explain any rename that isn't obvious. Keep behaviour identical. Once it reads clearly, we'll decide how to restructure.

A function full of d, res, and doStuff gets renamed to invoice, lineItems, and applyDiscounts. Suddenly it's clear that two unrelated jobs are tangled together — the natural split you couldn't see before now names itself, and the extraction is trivial.

Do the renames as their own commit, reviewed and merged on its own. Because a pure-rename diff is easy to verify, reviewers can approve it quickly, and the subsequent structural change lands as a small, focused diff on top of already-clear code.

• Bundling renames with structural moves, producing a huge diff where nobody can tell what actually changed.
• Renaming toward cleverness instead of clarity — a name should say what the thing is, not show off.
• Skipping the rename pass because it feels unproductive, then restructuring code you never actually understood.