A new programmer meets an unfamiliar codebase. It may be the sprawling, ivy-covered maze of long-running enterprise software, or it may be the latest in vibecoded expediency, a collection of local maxima with little coherent structure. Either way it's unfamiliar, full of bugs - and now the responsibility of a new mind.
One of the most useful things to do in this situation is to start writing fieldnotes, a term I've borrowed from the descriptive sciences. Quoth Wikipedia:
Fieldnotes refer to qualitative notes recorded by scientists or researchers in the course of field research, during or after their observation of a specific organism or phenomenon they are studying. The notes are intended to be read as evidence that gives meaning and aids in the understanding of the phenomenon.
If there's one that's sorely needed when working on legacy code, it's meaning and aids in understanding the phenomena
! It may seem that this is
largely a technical issue; the surface level problem of an unfamiliar
legacy codebase is, after all, the unfamiliar code. But it's the concerns above the technical which frame everything the new programmer faces:
- Why does the software exist; what business purpose does it serve?
- Who are the users, and what are they trying to accomplish?
- What are their workflows?
Now every bug report starts making more sense. There is a specification from which to base new tests, and a case for deleting old ones if what they test is not meaningful. Every feature request is now anchored in something tangible. And - with a little polish - these notes can form the basis of a Field Manual which can be used to help onboard others; A Pocket Guide to The Codebase.
That is not to say technical things should not be noted; but to me there's an order of importance - one easily becomes overwhelmed when facing tech without context, especially when it has real active users who at this point probably know it better than you do. But again, keep working "downward" towards the tech; external dependencies and deployments are most important, technical architecture is next, and work your way down from there as needed.
Guidelines for Writing Them
- Breadth is better than depth
- This is chiefly for the edification of the programmer; a sketched map of unfamiliar territory, the lay of the land. Do not get bogged down in details yet - sketches can be filled in and workflows refined in a "Just in Time" manner as you learn more.
- A document, not code comments
- Write them as a document, not in the code. Commit them of course, but as a standalone thing, you want something coherent to refer to without navigating between dozens of files.
- Top-heavy is better than bottom-heavy
- Fieldnotes are about giving you an overview, a context that is lacking. I am certainly not against adding more technical or code oriented notes - but the real value is in encoding information that may be hard to infer from reading the code.
Objections
"We don't have time to write!"
On the contrary, you don't have time not to. Nothing is less productive than blindly feeling about in a large, strange, unfamiliar codebase; "fixing" bugs you have no context for (ask me how I know 🙃). What I'm advising is not some luxury; it's the most pragmatic and efficient way to get issues resolved and features added.
Whatever a job description might have said about wanting programmers who can "Hit the ground running" with "N years of experience with technologies XYZ", every unfamiliar bit of software is going to have a ramp-up time. In my experience, the tech stack is the least important factor in this; it is the business domain and the idiosyncrasies of the codebase itself which dominate - exactly the things fieldnotes will help with.
"AI can do this for me"
As discussed, fieldnotes serve two purposes. The first is to augment the knowledge and capability of the person who wrote them. The second is to serve as the basis for a shared onboarding document to any new people or future maintainers. AI can serve neither of those goals; having an LLM write an artefact teaches you nothing, and no one wants to edit or read AI prose. This is not a polemic against AI as an assistant to your fieldnotes; they are nothing if not good readers and searchers; excellent at telling you which parts of the codebase are of interest for a particular query. But true understanding, words worth reading, these must ultimately be wrought by human hands.
"It will get out of sync with the code"
A very common sentiment, often - coincidentally enough - expressed by programmers who hate writing! In legacy code, feature development has almost always come to a crawl; things will go out of sync much slower than you think, until fundamentals start getting fixed. Again, I would deliberately keep technical details high level. They're a primer, an orientation for the deep code dives that will inevitably follow. Keeping it high level limits document churn, but of course as things change LLMs do a pretty good job of checking what's out of date.
A Confession and a Conclusion
It is here that I must come clean; my "Fieldnotes" are just "Software Requirements" in disguise. Writing things at a level of abstraction above the source code has fallen massively out of fashion in recent years; I worried if I wrote "requirements" people might recoil in fear, perhaps picturing massive stacks of printed paper no one ever reads. But my choice of fieldnotes is deliberate; keep them brief, concise, and useful. We don't have to choose between novels and nothing; there is a happy path, and - I hope you will agree - a useful one.