Where parallels cross

Interesting bits of life

Emacs as your code-compass: how stable is my code?

Too long; didn't read

Reliable things in life are important, so find the code that you can rely upon! Some code in your repository is left alone for a long time. That means that it is generally safe. Find it with code-compass c/show-stability-graph: you just need to look for white circles.

The problem

Say we have a repository that has overgrown in functionality. It contains all sort of things: from geolocation to authentication (and maybe even some eastern egg that some developer unexpectedly added in). What if we want to split this variegated functionality among multiple repositories? One approach is to cluster code by feature and then move these code clusters in new repositories. But what if people are actively working on these features? Shall we surprise them with our new structure? It would be amazing instead if find out the code that is stable and untouched: that is surely ripe to move to a better location!

It is a problem indeed

Finding stable parts of your code is convenient also from a quality perspective. Things that do no change for a long time are likely to have enough quality in them to avoid recent modification (or dead code, which is somewhat the same). In his book Software Design X-Rays, Adam Torhill writes: "The risk of a new bug decreases with every day that passes. That’s due to the interesting fact that the risk of software faults declines with the age of the code" 1.

This is interesting even for learning, because we can see what are the characteristics of this code to reproduce them. Typically the design of software produces stable code 2. If we just can learn from the previous maintainers how to design and implement stable code, we can have a code base that stays reliable.

And there is a solution

Code ages. The bad of this is that we gradually forget what the old code is doing, the good thing is that if old code stays untouched it is likely that is reliable. We saw that the hotspot tells us which parts of the code are really active and likely buggy. Code stability is basically the inverse of that analysis.

You can produce a stability graph with code-compass's command =c/show-stability-graph. The graph looks like the following:


The clearer the white the older is the last modification on the code. You can then see how easily it is to spot clusters of modules that have been left by themselves for a long time. If circles are blue it means that they have been modified recently. Apparently the Org module of Pandoc is still actively modified while the Docx is growing older and stable.

Again this analysis is interactive, let me show you how to run it:

By the way, be aware of the grey circles! These modules are neither stable nor unstable, which means they get changes sporadically. This may likely imply that people are modifying them without having a clear idea of the design decisions they originated with. And that may result in subtle errors!


So find out the safe zones in your code base. You can then move them in libraries if you need to. And maybe you can try to document the partially stable modules so you can decrease the chances that sporadic maintainers introduce errors. Just get code-compass, run c/show-stability-graph, and look for the white circles!

Happy aging!



Sometimes is designed so ugly that people avoid to touch that code at all cost, making it stable. You may say that is a feature.