Walking Through The Code

I’ve been thinking about code quality a bunch lately and the kinds of metrics that exist for how “clean” code is. Things like cyclomatic complexity, maintainability index, nesting depth, method length, and Halstead volume. They all provide some info, but they’ve also got issues. While the source code is the ultimate source of truth for what is, it’s by no means the full story. It can’t tell you what problem it’s solving, why it is the way it is, why it isn’t some other way, or what the foreseen but not yet handled problems are. And it’s particularly bad at helping someone understand the gestalt of it.

That’s where documentation comes in. The typical README.md can be good for the why’s. Why is it this way? Why isn’t it that way? Why are the domains split the way they are. There’s also usually some background on the problem being solved. Maybe even something about how the component can or should fit into the bigger picture. These are all great things and we should write them down for all of our components.

One thing I rarely see though, and wish I saw more of, is a walkthrough. How are control and data flow embodied by the actual code. Combining the details of class definition and control logic with the high level design by following a specific call or command from the user’s request until the work is done. You’ve done this as part of debugging. Before you can understand what went wrong with a bug, you had to step through the code to understand how the happy path worked. Only then can you try to figure out where things went wrong and do something about it.

You’ve certainly done this by yourself, and probably sometimes with someone more familiar with the code. It’s almost always easier to find your way through the code with a guide. The guide can help you stay on the main path and point out interesting and relevant things nearby along the way. They can provide context along the way that will help you understand the specific situation you’re looking in. The problem is, there might not be a guide available when you need one.

That’s where the walkthrough comes in. It’s not just a list of facts and details. Just like a museum self-guided tour, the walkthrough gives you an overview and context but lets you dig in to the thing that is most important to you. Which makes things easier for you the maintainer. Even if you were the one who wrote the walkthrough in the first place.