Course contentsShow
← Software Engineering
Lesson 381 of 1,93311. Code Quality and ReadabilityFree lesson

Maintaining Comments During Refactoring

Keep documentation synchronized with code changes and recognize when outdated comments become harmful.

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:

  1. Update immediately: Change comments in the same commit as code changes
  2. Delete outdated comments: If you extract logic to a new method, remove comments that no longer apply to the original location
  3. Move comments with code: When relocating a method, bring relevant documentation along
  4. 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.