Emacs can show us how files are historically related to each other, just use code-compass c/show-coupling-graph. In this post I explain how that helps you.

When I am maintaining a code base that is not mine, I always wonder: what would the writer of this code do in my place to extend it. So it turns out that after some head scratching and reading around, I resort to act. I add my test, the old tests pass, the pipeline is green. Everything seems fine, until... crash! The infamous end to end tests are not flaky this time: my modification broke one. I found the error, fix it, redeploy: pheeew, all is well what ends well. Then a moment of curiosity: let me check via magit if anybody else touched the same files lately. Aaargh! Exactly the same change I did a few weeks ago. And I spent 3 hours because I broke the end to end tests. If only I could see this extra file needed a change too!!!

Well, apart of learning from our ancestor maintainers, there is another reason for which visualizing the relationship between files over time. That is coupling of irrelevant modules. When two distinct files need always to change together for a reason, something is wrong with the design. Most likely there is some functionality that you can extract from both towards a new module. Discovering and acting on this design coupling will make you shine with your closer software architects (you need to show them though, because they are busy people), and more importantly will save you from the kind of forgetful behavior I wrote earlier. It is normal for new maintainers to be unaware of these hidden relations, and it is really a challenge that makes little sense: let's be tidy and just put things in their right place!

So let's skim through the theory once more. Git knows. Code under version control has another dimension you can access: time. A bit of Git-foo can already tell you a lot of how files have changed together during the life of the repository. Why is this information unused by our editors? Amazing question, let's fix the most adaptable editor ever to give the example!

Actually let me show you what we can do:

The hedge bundling graph is showing you all the files of the repository.

The links show you that files have a temporal relationship: when one changed the other file changed too. The denser the line the more often it changed together. The color of the lines indicate which changed before the other, and I did not find a use for that yet. You will notice that often the coupled files are a module and its test: we expect that.

Another interesting use case of this is learning about the code base: this graph relationships helps grouping modules by their meaning. For example the main cluster of relationships in the pandoc's graph represent groups of test files that are likely used to test file conversion from one format to the other. I use this graph myself to complement the structure of a repositories (I mean the directory tree) with the structure of the changes over the repository.

Another thing I do with this graph, or better the information underneath is: to let Emacs find the files I should change next! I shall show you in my next post how a mix of projectile and code-compass can lighten the way forward.

So the hunt is open! Grab your code-compass, run c/show-coupling-graph over your favourite repository, and let your editor finally do more than showing you a flat file with annotations! What are you going to discover? Please make the best you can out of this analysis: you really can maintain your repository more effectively now.

Happy decoupling! in your code.