To modernize software when no documentation exists, rebuild the missing knowledge first and change the code second. Read the legacy codebase, its history, its database and its logs, and ask the people who use it. Then pin down its behavior with tests and record its business rules. Only then replace it, one part at a time. This guide is for a CIO who inherited an undocumented legacy system, such as a distributor's order system nobody inside can explain. It covers where the missing documentation hides, how tests make legacy code safe to change, how to record business rules, and when to replace a part. It matters because a change to code nobody understands can remove a behavior the company still relies on.
The Gnar Company reads this kind of code in its free code audit. The audit page describes the work: "At The Gnar Company, senior engineers in the U.S. read the code, with help from an AI tool Gnar built, and explain what they find." Ask for the code audit. No fee, and it can come back saying your codebase is in reasonable shape.
How do you modernize software when no documentation exists?#
Modernize legacy code that has no documentation in five steps, in this order: copy it, read it from the outside in, pin its behavior with tests, record its business rules, then change one part at a time. Steps two to four rebuild the documentation that was never written. The fifth step is where modernizing legacy systems actually starts.
These steps are general advice, and steps two to five each have a section below:
- Copy the code and the data. Put the legacy codebase in a repository the company controls. Get a copy of the database you can read without touching production.
- Read it from the outside in. Start with what you can see: the screens, the database and the logs. Then read the code behind them.
- Pin down what it does with tests. Identify the part that will change first, and focus the first tests on recording its behavior today.
- Record the business rules. Record each rule with the place it came from, and have the person who owns that process confirm it.
- Change one part at a time. Clean up the parts worth keeping and replace the rest. Keep the old part in place until the new one passes the same tests.
The order in step 2 comes from a Thoughtworks case study on martinfowler.com, From Black Box to Blueprint. Its first practice reads: "Begin with what you can see and trust: screens, data schemas, logs." On its audit page, Gnar starts its answer to this question this way: "Start by understanding what the code does."
What is legacy code?#
Legacy code, in Michael Feathers' strict definition, is "code that we've gotten from someone else." His own working definition, from the preface of Working Effectively with Legacy Code, is shorter: "To me, legacy code is simply code without tests" (Pearson sample pages).
He explains why tests decide it: "Without them, we really don't know if our code is getting better or worse." For a CIO who inherited an order system, the first definition is already true. Whether the second is true is one of the first things to check.
Which legacy languages do old systems still run on?#
Some legacy systems run on languages that fewer people can still support, and the U.S. Government Accountability Office has reported federal systems written in COBOL and in assembly language. Its 2016 report describes COBOL as "a programming language developed in the 1950s and 1960s". The same report says "Agencies reported using several systems that have components that are, in some cases, at least 50 years old".
GAO's 2019 report says COBOL has "a dwindling number of people available with the skills needed to support it."
What is technical debt?#
Technical debt is Ward Cunningham's metaphor for the ongoing cost of code that is not quite right, from his 1992 experience report. "Shipping first time code is like going into debt," he wrote. "Every minute spent on not-quite-right code counts as interest on that debt" (Cunningham, OOPSLA 1992).
As general advice, missing notes raise the interest, because every change starts with someone working out what the code does.
Why is undocumented legacy code risky to change?#
Undocumented legacy code is risky to change because nobody can say which of its behaviors the company depends on. Undocumented here means no architecture notes, no design documents and few or no code comments. Michael Feathers puts it this way: "When a system goes into production, in a way, it becomes its own specification" (Feathers on characterization testing).
He once fixed a bug that users turned out to depend on. "They didn't think it was a bug, they thought it was a feature."
In the Thoughtworks case study, the engineers set out to see whether AI could "create a functional specification of the existing system with sufficient detail to drive the implementation of a replacement system". It describes the systems it has in mind plainly. "Documentation is either missing or hopelessly out of sync with reality. The people who wrote the code have long since moved on." The system used a three tier design, web, application and database, and the team wrote that "This architecture pattern gave us a jump start even without source repo".
Understanding legacy code, like any code, takes a large share of developers' time. Xin Xia and coauthors observed 79 professional developers on 7 projects at two IT companies in China (Xia et al., IEEE TSE). On average, about 58% of the developers' time went to program comprehension, the work of understanding code. The study concludes that "developers working on maintenance projects spend more time on program comprehension than these working on development projects". As general advice, an undocumented system leaves new engineers even more of that tracing to do.
Where does the missing documentation hide in a legacy codebase?#
The missing knowledge is spread across seven places: code comments, version history, package files, the database, logs, the screens and the people who use the system. Read them together. The case study's rule is "Never rely on a single artifact."
| Where to look | What it can tell you | Source |
|---|---|---|
| Code comments | The most common form of reference documentation | Software Engineering at Google, chapter 10 |
| Version history | The revision that last modified each line | The Git manual page for git blame |
| Package files | The ecosystems and packages the code depends on | GitHub Docs on the dependency graph |
| The database | Stored procedures and triggers that encode business rules | From Black Box to Blueprint |
| Logs and traces | Timestamped records, and the path a request takes | OpenTelemetry docs |
| The screens | The view of functionality users see on screen | From Black Box to Blueprint |
| The people who use it | Answers to the questions that tests raise | Feathers on characterization testing |
The git blame command, for example, "Annotates each line in the given file with information from the revision which last modified the line" (Git manual). In the Thoughtworks case, the database held much of the logic: "Stored procedures and triggers encode decades of accumulated business rules." Where code comments exist, read them alongside the code. Software Engineering at Google says "Code comments are the most common form of reference documentation that an engineer must maintain", and that "good comments help out a great deal when you're staring at code you wrote two years ago, trying to figure out what's wrong".
What do dependency mapping tools show?#
A dependency mapping tool such as GitHub's dependency graph shows which outside packages a legacy codebase relies on. For a private company repository, it does not show which projects rely on the code: GitHub says that information "is not reported for private repositories". It lists "Dependencies, the ecosystems and packages it depends on" and, for public repositories only, "Dependents, the repositories and packages that depend on it" (GitHub Docs).
The graph is built from "the manifest and lock files stored in a repository". As general advice, in legacy codebases, map the connections to your other systems separately, from the code and the database.
What can logging tools show about a running legacy system?#
Logging and monitoring tools show what a legacy system actually does while it runs in production. OpenTelemetry, whose stated purpose is "to collect, process, and export signals", defines a log as "a timestamped text record, either structured (recommended) or unstructured, with optional metadata" (OpenTelemetry logs).
Google's SRE book calls monitoring based on a system's internals, including logs, white-box monitoring. It says white-box monitoring "allows detection of imminent problems, failures masked by retries, and so forth", and that "When collecting telemetry for debugging, white-box monitoring is essential."
How do tests make undocumented legacy code safe to change?#
Tests make undocumented code safe to change by recording what it does today, so engineers can run them after each change and see whether that behavior moved. In his 2002 paper, Feathers calls these tests a covering, and he sets the standard plainly: "The key thing is that correct behavior is defined by what the set of classes did yesterday, not by any external standard of correctness."
He also says "Systems that are already deployed often require far more diligent covering because the cost of errors is significantly higher."
His book names the usual challenge: "When you start to try to pull out individual classes for unit testing, often you have to break a lot of dependencies". On his blog, he writes about a related method, characterization testing. "The hardest part is breaking dependencies around a piece of code well enough to be able to exercise it in a test harness." He advises keeping a test that shows odd behavior: "If you haven't determined that the behavior you've uncovered is a bug, it's often a good idea to leave the test in place."
For the new code that replaces each part, Gnar's code migrations page sets this standard: "The new code comes with automated tests, small programs that check it still works. A second engineer reviews it too."
What is refactoring?#
Refactoring, in Martin Fowler's definition, is "a disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior" (refactoring.com).
As general advice, this is why tests come before refactoring legacy code that nobody documented. Without them, nobody can show that the external behavior stayed the same, so check the test coverage of a part before you refactor it. The same site explains why teams refactor at all: "When a software system is successful, there is always a need to keep enhancing it".
What can security scanning tools find in legacy code?#
Static application security testing (SAST) tools, one kind of static analysis, scan source or compiled code to help identify security flaws in a legacy codebase. OWASP lists their limits. Its page on these tools says they are "Frequently unable to find configuration issues, since they are not represented in the code" (OWASP). The same page lists a strength: such tools "can be run repeatedly (as with nightly builds or continuous integration)".
How do you write down the business rules nobody recorded?#
Write each business rule as a short example with a starting state, an action and a result, and note where in the code or data it came from, so the context travels with it. Then the person who owns that process confirms the rule or corrects it.
Martin Fowler's page on Given When Then explains the format. "The given part describes the state of the world before you begin the behavior you're specifying in this scenario." The when part is the behavior itself, and "the then section describes the changes you expect due to the specified behavior."
The Thoughtworks case study adds two practices. One is "Confirm every hypothesis across at least two independent sources". The other is to "Track where every piece of inferred knowledge comes from". Gnar's guide to using Claude Code on a legacy system explains why the confirming step needs a person: "Business rules are hard because the code records what the system does, and only your people know what it is supposed to do."
Gnar's code migrations page states where its own reading starts: "Where nobody wrote down how the code works, we work it out from the code itself."
What does this look like for a distributor's order system?#
For a distributor's order system, the five steps run from a copy of the code to one replaced set of screens. In this illustrative example, a distributor of industrial fasteners runs a 15 year old order entry system with no documentation. The developer who built it is gone, and the CIO's first project is to replace the order screens.
- Copy. The engineers move the legacy codebase into a company repository. They restore a copy of the database into a test environment.
- Read from the outside in. They study the screens the order desk uses, the order tables and the stored procedures behind them, to see how different parts of the system connect. Then they read the application logs and the legacy codebase.
- Test. Before touching the order screens, they write tests that record what the system does today with a short order: 1,000 boxes of bolts with 400 in stock.
- Record the rule. The tests show that the system ships 400 and backorders 600, unless the customer is flagged ship complete. The written rule reads: given a customer without that flag, when a line is short, then ship what is in stock and backorder the rest. It names the stored procedure it came from, and the order desk manager confirms it.
- Change one part. The new order screens are built on the same database. The old screens stay in place until the new ones pass the same tests.
Should you rewrite undocumented legacy code or refactor it?#
As general advice, decide part by part: compare what each part costs to fix with what it costs to replace, and rewrite a part only after its rules are recorded and tested. Martin Fowler explains the risk of a full replacement on his strangler fig page: "Replacements seem easy to specify, but often it's hard to figure out the details of existing behavior."
He goes on: "What's worse, much of that behavior is stuff that isn't really wanted, so building it is a waste." The method he and his colleagues prefer "is to do a gradual process of modernization."
Gnar's code migrations page says: "For each part, we compare what it costs to fix with what it costs to replace." When the answer is a rebuild, the audit page explains how the old code is used. "If a rebuild follows, The Gnar Company turns the old code into a written plan for the new software. Then it builds from that plan. It does not copy the old code line by line."
How did the AARP Foundation rebuild start from code another firm wrote?#
Gnar's AARP Foundation work began with an audit of tools another firm had built, then a takeover of the codebase and requirements gathering before the rebuild. The case study says "The tools launched in 2019 with a different development partner".
Gnar's audit found problems including "no integrated testing". In the first phase, the case study says, "we took ownership of the codebase from the previous firm, stabilized the current tools so they could be used securely, and gathered requirements for the rebuild."
The next phase used those requirements. "Using those requirements, we rebuilt the existing tools with testing, security, and scalability built in from the first commit." Gnar rebuilt 14 tools on React and Ruby on Rails, with 40% fewer clicks to complete an application, on average.
How do you keep a modernized system documented?#
Keep the documentation next to the code and change it whenever the code changes, so the next team does not start from nothing. Software Engineering at Google says "Quality documentation has tremendous benefits for an engineering organization". The same chapter says documentation "should, as much as possible, be treated as code" (chapter 10). It also says "Onboarding new members to a team or code base takes much less effort if the process is clearly documented." And it adds: "Often, the writing of the documentation itself leads engineers to reevaluate design decisions that otherwise wouldn't be questioned". Among the benefits it lists for the writer: "It will prompt fewer questions from other users".
The first four items below quote that chapter's list. The fifth quotes Google's style guide page, and the last quotes two Gnar service pages.
- Keep it in source control. The chapter says documentation should "Be placed under source control".
- Give it owners. It should "Have clear ownership responsible for maintaining the docs".
- Review it with the code. It should "Undergo reviews for changes (and change with the code it documents)".
- Track its problems as bugs. It should "Have issues tracked, as bugs are tracked in code".
- Use one coding style. Google's style guide page says "It is much easier to understand a large codebase when all the code in it is in a consistent style."
- Get it handed over. Gnar's ERP and order management page says "The codebase is yours, in your repository, documented for hand-off." Its code migrations page says "The code stays yours, with written notes so your team can take it over."
Where does Gnar's free code audit fit?#
Gnar's free code audit is an outside reading of the code, done before anyone talks about a rebuild. The audit page says "We read the code before anyone talks about a rebuild," and it covers "Your own team's code, or code someone left you."
The code migrations page lists what comes back: "You get back a ranked list: the risks, the easy fixes and your realistic options. It can also come back saying your code is fine." The step after it is optional. "If you go ahead, the next stage is paid planning, called Gnar Discovery and Design. It costs a fixed $20,000 for four weeks, up to $30,000 for six weeks." The Discovery page lists the same two tiers.
Gnar also says when it is not needed: "If your own team has the capacity and the direction, you do not need us".


