Keep Name Current

keep-name-current

Reader Locality Documentation Source Truth

Summary

Names that preserve old intent make readers distrust the code or documentation around them. Rename when the concept changes enough that the old name now teaches the wrong model.

Problem

Names become stale when responsibility changes. A stale name forces readers to choose between trusting the word and reading the implementation.

Preferred Move

Rename code when its responsibility changes. Keep broad renames separate from behavior changes when the rename would otherwise hide the rule change.

Tradeoff

Public names, serialized names, and widely used APIs have compatibility cost. Rename them only with the migration and communication that the boundary requires.

Agent Instruction

When code changes responsibility, update the name so future readers do not rely on stale
vocabulary. Separate broad renames from behavior changes.

Examples

Bad: the name still says "active" after the rule becomes visibility.

let active_patterns = patterns
    .iter()
    .filter(|pattern| pattern.status().is_visible());

Good: the name follows the current responsibility.

let visible_patterns = patterns
    .iter()
    .filter(|pattern| pattern.status().is_visible());

References

Source	Use	Note
Rename Variable	`supports`	Rename when a name no longer communicates intent.
C-COMMON-TRAITS	`adapts`	Rust APIs should use names callers recognize.