top of page

Rename Symbol Safely — Refactoring Patterns, Part 6

Shift Quality Editorial
Jul 30
2 min read

Updated: Oct 4

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