Last time we left here with some introductory thoughts about code comprehension and mental models. Let's five in a little deeper this time.

To internalize a complicated system we first need to divide this task into chunks. Different modules, layers, classes, processes - all of these can help understand what do all the separate piece of the system do and how they interact with each other.

Essentially, we're after three things:

  • What are the pieces?
  • What do they do?
  • How do they interact?

For small systems it's usually enough to go through this once and it will be sufficient. However, more complex designs need a recursive application of this approach. Split the application into pieces, describe them and then split each piece again and describe the workings of the inner pieces and so on, until we've dissected it down to trivial bits.

At the end of this process we will have basically onboarded our brains into this new codebase we're getting involved in.

This process we've described already is sounding very reliant on structure and patterns. These kinds of things often benefit from having tools to uphold the structure, provide guidance for the newcomers and take care of all the minutiae of keeping such a system running and effective.

The tools are all around us in the process of software development. Continuous integration tools, issue tracking tools and even libraries and frameworks that we use for development.

Next time we'll check out some potential approaches for using these kinds of structure- and pattern- based tools for documentation.

Arthur 👋