Identify the constraint rather than the age

A recently generated module with no owner or reliable checks can be harder to change than a decade-old service with clear interfaces. Describe the concrete obstacle: unsupported runtime, undocumented calculation, coupled modules, or fragile deployment. This turns a broad label into an investigation the team can act on.

Illustrative scenario: an old invoicing service runs reliably, but only one person understands a tax exception embedded in a long function. The immediate risk is knowledge concentration and unverified behavior. Replacing its language before documenting the exception could preserve neither the rule nor the business outcome.

Build a safe understanding of current behavior

Map callers, inputs, storage, and external effects before restructuring the code. Capture representative outputs and important edge cases in characterization tests. Treat observed behavior as evidence, then ask a domain owner whether surprising behavior is an intentional rule, an accidental dependency, or a defect.

Establish a reproducible build and a way to run relevant checks. Document configuration and dependency versions required to reproduce the environment. When setup depends on undocumented local files or manual steps, fixing that operational uncertainty may enable safer change before any architectural work begins.

Choose the smallest useful intervention

Refactor a bounded area when its behavior should remain stable and the implementation can be improved incrementally. Upgrade a dependency when support risk dominates. Consider replacement when the existing component cannot meet required constraints, while accounting for hidden behavior, migration, and ongoing operation during transition.

Prioritize frequently changed or high-impact paths rather than trying to modernize every old file. Record the expected benefit, verification approach, and owner. A quiet stable module may deserve documentation and monitoring, while a heavily changed boundary may justify deeper restructuring supported by focused tests.

Working sheet

Legacy constraints and first moves
ConstraintFirst useful moveEvidence of progress
Missing behavior knowledgeCharacterize critical workflowsReviewed examples and tests
Unsupported dependencyMap upgrade compatibilityBuild and integration rehearsal
Fragile deploymentDocument and automate release stepsRepeatable deployment in test environment
Tangled business logicIsolate one policy boundaryFocused change without unrelated edits
Download this worksheet (CSV)

Questions about what is legacy code?

Does legacy code mean bad code?

No. It describes a maintenance context. Evaluate actual constraints and change risk instead of using age as a quality score.

Should legacy code always be rewritten?

No. Refactoring, documentation, upgrades, and targeted replacement may address the constraint with less migration risk.

How should I use the working sheet?

Download the CSV and replace the sample rows with evidence from your repository. Record a clear acceptance check and an owner for each item. Keep unresolved assumptions visible rather than treating the example as a completed assessment.

Sources and further reading

Examples are illustrative. They are not customer results, security guarantees, or a substitute for checking the documentation for your installed version.

Make the next change verifiable.

Getzilla is an open source workflow for changes to existing repositories. Inspect the project, define acceptance checks, and keep independent review in the loop.

See the repository workflow See current access and pricing