Table of Contents for

Your Code as a Crime Scene

Grow Your Mental Maps

Remember how we discussed geographical offender profiling back in ​Learn Geographical Profiling of Crimes​? We built our hotspot analyses based on the idea that just as we spot patterns in the movement of criminals, our version-control data lets us identify patterns in the changes we make to the codebase. What I didn’t mention back then is that the movement of offenders is constrained by a concept called mental maps.

A mental map is our subjective view of a specific geographic area. Our mental maps deviate from how a real map would look. For example, geographical hindrances such as highways and rivers often constrain and skew our perception of an area. In the small town where I grew up, it took me years to venture across the heavily trafficked road that cut through the city. As a consequence, my mental map ended at that the street. It was the edge of the world. Similarly, the mental maps of criminals shape where their crimes take place.

We programmers have mental maps, too. Over time, at least when we work with others, we tend to specialize and get to know some parts of the system better than others. These knowledge barriers shape our perception of the system—our mental maps constrain our view of the system to the parts we know. Let’s see how we can tear them down.

Explore Your Knowledge Map

Imagine for a moment that you had a map of the individual knowledge distribution in your organization. No, no—not some out-of-date Excel file that’s stashed away on the intranet. To be useful, the information has to be based on how we actually work. In reality, in code.

The concept we’ll develop is a knowledge map. A knowledge map lets you find the right people to discuss a piece of code, fix hotspots, and help out with debugging. Let’s see how the end result looks in the figure, so we know where we’re heading.

---

Figure 1. Knowledge map showing the main developer (indicated by color) of each module.

This knowledge map of the programming language Scala is based on the same concept as the fractal figures, as each programmer is assigned a color. This lets us reason about knowledge distribution on a system level. For example, the map shows that components such as scaladoc (generates API documentation), asm (Java bytecode manipulation), and reflect (dynamic type inspection and manipulation) seem to be in the hands of a single developer—there’s little knowledge distribution. In contrast, other components, such as the compiler, exhibit a shared effort, with contributions from multiple developers.

The visualization is based on interactive enclosure diagrams, just like we used back in ​Visualize Hotspots​. Have a look at the visualization samples you downloaded from the Code Maat distribution site.^[34] There’s a scala directory inside that bundle. Open a command prompt in that directory and launch Python’s SimpleHTTPServer:

Now you can point your browser to http://localhost:8888/scala_knowledge.html to view the Scala knowledge map. The interactive visualization lets you zoom in on individual components for a detailed examination. Let’s see what the map tells us about the Scala compiler.

Pretend for a moment that we join this project and need to make a change to the typechecker. Our map immediately points us to the green developer as the correct person to discuss our proposed design with. If we come across some task in the backend instead, green may still be able to help us out, but we’re more likely to get the right expertise if we involve the light-blue developer, too. All right, let’s see how you can create this map.