Maintaining Comments During Refactoring
You'll learn: How to keep your documentation accurate and valuable when restructuring code, and why stale comments can be worse than no comments at all.
The Synchronization Challenge
When you refactor code—extracting methods, renaming variables, moving logic—your comments don't automatically update with it. This creates a dangerous gap: code evolves, but comments remain frozen in time. Think of it like updating a building's layout but never changing the floor directory—people will get lost following outdated instructions.
When Comments Become Harmful
Outdated comments actively mislead developers. If a comment says "calculates total price including tax" but the refactored method only calculates the subtotal (tax moved elsewhere), future maintainers will trust the lie. They might skip reading the actual code, make wrong assumptions, or waste time debugging phantom problems.
Worse than helpful: An incorrect comment is more dangerous than no comment because developers naturally trust documentation over questioning every line of code.
Keeping Comments in Sync
When refactoring:
- Update immediately: Change comments in the same commit as code changes
- Delete outdated comments: If you extract logic to a new method, remove comments that no longer apply to the original location
- Move comments with code: When relocating a method, bring relevant documentation along
- Question necessity: After refactoring to clearer names and structure (self-documenting code), ask if comments are still needed
The Review Checkpoint
Before committing refactored code, scan every comment in modified files. Ask: "Is this still true?" If uncertain, delete it—silence beats misinformation.
Key Takeaway: Comments are code documentation, not code itself—they won't break your build when wrong, but they'll break your team's understanding. Treat comment maintenance as mandatory, not optional, during refactoring.