The Codebase You Inherited and the Person Who Left No Comments

The Codebase You Inherited and the Person Who Left No Comments

The codebase has no comments. Not a single one. Not a docstring, not an inline explanation, not even a TODO. Three thousand lines of Python, and the only text that isn't code is the variable names — which are, at least, descriptive. You've been staring at it for three days and you're starting to understand why there are no comments.

The person who wrote this didn't need comments. They knew exactly what every line did. The code was transparent to them in a way it isn't transparent to you, and they saw no reason to explain what was obvious.

This is the most common reason for undocumented code, and it's the hardest to be angry about.

What the Absence of Comments Reveals

A codebase with no comments tells you something about the person who wrote it. Not that they were lazy — lazy programmers write comments, because comments are easier than thinking. The absence of comments usually means one of three things: the code was written by someone who thought in code natively and didn't experience the need for translation; the code was written under time pressure so extreme that documentation felt like a luxury; or the code was written by someone who intended to come back and document it later and never did.

The third case is the most common. The intention was there. The time wasn't.

The openedterminal archive has some writing on this — on the gap between what developers intend to do and what they actually do, and how that gap is usually filled by whoever inherits the code. You are now filling that gap.

Reading Undocumented Code

The first thing to do is stop trying to understand everything at once. Undocumented code is not a puzzle to be solved in one sitting. It's a landscape to be explored gradually, with the understanding that you will get lost and that getting lost is part of the process.

Start with the entry points. Find where the code starts — the main function, the API endpoints, the event handlers. Work outward from there. Don't try to understand a function before you understand why it's being called.

Write comments as you go. Not for the original author — they're gone. For yourself, and for whoever comes after you. The comments you write while learning the code are often the most useful comments, because they capture the questions you had and the answers you found. Future readers will have the same questions.

The calitoycore approach to this is systematic: read the tests first. Tests are documentation. They tell you what the code is supposed to do, even when the code itself doesn't explain how it does it. If there are no tests — and in a codebase with no comments, there often aren't — that's a different problem.

The Variable Names as Archaeology

In this codebase, the variable names are the only documentation. And they're actually good — descriptive, consistent, following a naming convention that reveals something about how the original author thought about the problem.

Variable names are a window into the mental model of the person who wrote the code. The names they chose reveal what they thought was important, what they thought was obvious, what they thought needed to be distinguished from what. Reading the variable names carefully is a form of archaeology — you're reconstructing a mind from its artifacts.

The maker mindset writing has touched on this — on how the choices you make in your work reveal things about how you think, even when you're not trying to communicate. The undocumented codebase is a portrait of its author. You just have to learn to read it.

What You Owe the Next Person

When you're done with this codebase — when you've made your changes, fixed your bugs, added your features — you will leave it in better shape than you found it. Not because you're a better person than the original author. Because you had the experience of inheriting undocumented code, and you know what that costs.

Write the comments. Write the docstrings. Write the README that explains why the code exists, not just what it does. The tarosyn dev log has a good example of this — the documentation written after the fact, when the original developer finally had time to explain what they'd built. It's better than nothing. It's not as good as documentation written while building.

The next person who inherits your code will thank you. They won't know your name. They'll thank you anyway.