What is it that we're grasping at here? What is the goal that we're hurling ourselves towards? The answer is simple.

Code comprehension.

Most issues in coding are related to not understanding code or not understanding it correctly. From syntax rules to high-level architecture patterns. Even if all of our code is neatly split into modules or objects and those are isolated from each other. To fix a non-trivial issue it still takes knowledge of how all of these pieces work together, how they're layered, where are things allowed to happen and where they're out of place.

Let's take a look at a simple example of a bug.

Program: a single page web app that's used to manage a database of animals in a zoo

Problem: we've added a new class of animals called 'Monkeys'. Then we've added two new animals, John and Herbie, who are both Monkeys. Now, in the main list of all animals of the zoo all animals are called by their class+name. So there's Lion Miles, Parrot Ella and Crocodile Mingus. But for some reason our two new monkeys are listed to John and Herbie, not as Monkey John and Monkey Herbie.

We've got a bug on our hands. Now the chase begins. Is the problem in the database because the names should have concatenated with the class when saving? Are they combined in the UI at the very last moment? Maybe there's a domain model called Animal (cheers, university!) that has this combining logic in the constructor? Or maybe there's a formatter that's used when assembling the final viewmodel?

It takes familiarity with the code to answer this question with any degree of confidence.

This, of course, is a highly contrived example and all of these monkey-related shenanigans could have been probably avoided by just using better software design practices. But still, I hope the reader can glimpse what I'm trying to get at here.

This "familiarity with the code" is what I'll call a mental model from now on. To arrive at a stable mental model it takes either a great deal of trial and error while working on the program or teammates that are great at explaining things and willing to do so.

Both of these things ensure that the information is not just heard, but is deeply internalized and can be used on an intuitive level, without a meticulous recalling of details.

This process is what code comprehension really is.

The bigger picture here at KeelDocs is to aid developers in this process. We want to speed up code comprehension, make it less demanding. Enable fellow devs to ramp up in a new project quickly and without painstaking memorization of seemingly arbitrary details.

Join me next time, when we will take a look at possible ways to speed up code comprehension!

Arthur 👋