top of page

Rename Symbol Safely — Refactoring Patterns, Part 6

Shawn West
Jul 30
2 min read
Refactoring Patterns · Part 6

A bad name taxes every future reader, but renaming feels risky — which is why so much code keeps a name that stopped being accurate three features ago. It doesn't have to be risky. This walks through renaming a symbol safely: using your IDE's rename (not grep-and-replace), handling public APIs and database columns that can't just change, and doing it as a routine habit instead of a scary event.

Names compound interest. Wrong name today = confusion tomorrow.

Step 1: Why It Matters (15 min)

Code reads more than it's written.

A misleading name:

  • Wastes reader time

  • Misleads new engineers

  • Hides intent

  • Encourages bugs

Renaming = high-impact refactor.

Step 2: Use IDE (15 min)

F2 (most IDEs)
Right-click → Rename Symbol

Or:

  • VS Code: F2

  • IntelliJ: Shift+F6

  • Vim/LSP: <leader>rn

IDE updates all references safely. Strings + comments: ask before changing.

Step 3: Don't grep-replace (15 min)

❌ sed -i 's/orderTotal/total/g'

Why bad:

  • Hits unrelated strings

  • Doesn't respect scope

  • Doesn't handle dynamic references (reflection)

  • No type checks

Use language-aware tooling.

Step 4: Public API (15 min)

Internal symbols: safe to rename freely.

Public APIs (used by callers outside your code):

  • Deprecate old name; add alias

  • Migrate callers over time

  • Remove old later

Breaking renames = broken consumers.

Step 5: Database / Migration Concerns (15 min)

Rename a column / table: not refactoring; it's a schema migration.

  • Add new column

  • Backfill data

  • Migrate writers

  • Migrate readers

  • Drop old

(Data migrations covered separately.)

Step 6: Multi-Repo Renames (15 min)

Symbol crosses repos (e.g., gRPC service name):

  • Coordinate across teams

  • Long deprecation window

  • Use codemod tools

Atomic rename across many repos: not realistic.

Step 7: Naming Tips (15 min)

  • Verb for functions / methods (calculateTotal)

  • Noun for types / vars (order, customer)

  • Avoid abbreviations (except super common)

  • Domain vocabulary (ubiquitous language)

  • Length proportional to scope

Loop var i ok. Class var i: wrong.

Step 8: Boolean Naming (15 min)

isReady, hasPaid, canShip.

Not: ready, paid, ship (ambiguous).

Helps reader parse conditionals.

Step 9: Reverse Engineering (15 min)

Bad name from history:

  • Investigate: why this name?

  • Often: legacy concept; meaning shifted

  • Update name to current reality

  • Add domain glossary entry

Renames teach you about your codebase.

Step 10: Routine (15 min)

Rename as you go:

  • Spot misleading name

  • Rename via IDE

  • Commit

  • Continue

Small, frequent renames > big sweep refactors.

What You Just Did

Rename Symbol Safely: why it matters, use IDE, don't grep-replace, public API, database / migration concerns, multi-repo renames, naming tips, boolean naming, reverse engineering, routine.

Common Failure Modes

grep-replace. Catches strings; misses dynamic refs.

Rename public API without deprecation. Break callers.

Cryptic abbreviations. Renamed but still bad.

Don't update docs. Inconsistency.

Big-bang rename. Risk + review pain.

Continue the Refactoring Patterns path

Part of the Refactoring Patterns learning path.

bottom of page