Practicing code archaeology

As a software engineer, you may find yourself working on a large, old codebase that predates you or any member of your team. In my experience, engineers working on codebases like this get a little skittish: they are afraid to delete things, clean up code, or remove things out of fear that they may be tearing down a secretly load-bearing Chesterton's fence.

On the one hand, this is a good impulse: "if it ain't broke, don't fix it." On the other, sometimes it can inhibit engineers. If a codebase requires new features or you are dealing with a thorny bug, confusing, old code is something you must understand. Furthermore, in an actively-developed codebase, old, dead code can confuse engineers working on it (is this code actually used? What is it for?) and messes have a tendency to proliferate. Engineers working on these codebases may develop a fear that if they touch the wrong thing, everything will come crashing down, and this can slow down new feature development.

The solution to this is to develop an understanding of why code was put into place, in other words, learning how to become a code archaeologist. Git provides us with a number of tools to do this. The most valuable, in my view, is git log -L

This git flag allows you to see the development of a single function. If you encounter a confusing, poorly-documented bit of code in a codebase and want to understand what it did, this command will give you the "story" of how that function changed over time: who changed it, when the changed it, and, hopefully, why. Experiment with this command on a few long-standing or complex functions in your codebase: I have found it tremendously helpful.

By reading the history of a function, or a module, hopefully you can learn its "story": when and why each line of code was added, and what the code is intended to do. Once you have this understanding, you can debug, change, or delete long-standing code with confidence.

There are two things you can do to set up future archaeologists for success. First: comment heavily. You don't need to explain what code does, but explaining why you made some strange architectural decision allows a future engineer to more confidently change or remove it when those conditions for its existence are no longer required.

Secondly, write good commit messages. A good commit message (written by hand, not LLM) should provide any information that is not in the code itself: i.e. why a change was made, what bug it was intended to fix or what problem it was intended to solve. This should link to external documentation, if it exists. Even a sentence or two explaining a change can be tremendously helpful for an engineer who, four years later, is trying to work out what the purpose of some inscrutable if block is.