INTEGU uses cookies to personalize your experience and provide traceability for affiliate links. By using the website, you agree to these terms and conditions. To learn more see the privacy policy page.
Your Code As A Crime Scene
Book Review
Menu
Book Review: Your Code As A Crime Scene
Your Code as a Crime Scene (Affliate Link) is essentially a book about utilization of version control systems (VCS) to analyze and determine hotspots in the codebase. Whether this is due to weird code couplings, high variations of authors on a single class, code complexity, or something entirely else, can be determined by using the source code analysis tool CodeMaat. A tool conveniently developed by the author, Adam Tornhill. The tool is demonstrated throughout the book and provides insight information about the state of the codebase.
It is worth noting that CodeMaat has, after the book’s publication, evolved from a command line utility, and into a full-blown code quality analysis webpage, with user friendly UI and storage plans. The new edition is called CodeScene and can be accessed for free on private or small-scale projects.
It should be noted that Code City is not part of the CodeMaat toolkit, but that Adam uses it to provide a visualization of an entire codebase’s quality of code. CodeMaat also implements a visualization tool, which essentially illustrate the same points. CodeMaat’s visualization is based on a circular representation as can be seen below.
So why is it called “Your Code as a Crime Scene”? Within nearly all chapters, Adam starts by providing a summary of a fictional or real crime case, in which he then draws parallel to the specific problem which is analyzed in the chapter. The value of this comparison is sometimes difficult to evaluate. However, it creates a break from reading about VCS commands and deducing tables and charts, which can sometimes be refreshing.
Key Takeawys
Hotspots
Hotspots are places in the code, where both the frequency of commits and the complexity of the classes are high. In this case, the complexity is measured by the amount of methods or lines of code (LOC). Utilities like “Code City” can be used to illustrate these hotspots.
Code City creates a visualization of the codebase, where as each block is equivalent of a package, and the height scale based on the number of methods is the package. Meanwhile the color of the block determines the frequency of commits. If you want to learn more, I suggest checking it out for yourself.
Conjunctions
Methods or Class with conjunctions in their name, should ALWAYS be split into two. This has nothing to do with VCS code analysis, but as Adam mentions, it is often that hotspots are attracted to classes, which serve multiple purposes. Additionally, I know at least one other developer who would agree with me on this point. If you are unsure of who I am referring to, I suggest you checkout my other post to get a hint.
Complexity Level
After using Code City or CodeMaat to gain an overview of the codebase, it is important to remove false positives (classes expected to change frequently e.g build.gradle) and determine if a class is already on a path of improvement. A method for determine the future of the class, is to look on a graph of its complexity level over the commits of the past. If the complexity is rising, it is clearly a hotspot, while if it is lowering, it is probably under control (perhaps it is still wise to investigate).
Temporary Couplings Of Classes
Some classes are meant to be altered together. If you add a new button to the view component of an MVC pattern, it is likely that you want to add a new listener to the controller, which will be hooked up with the button. These couplings are expected. However, sometimes two classes are coupled together in their commit history, without there being any logical connection. This might be a sign of bad code implementation. The source of this problem might come of many malpractices, e.g. mishandling of shared utility classes or singleton classes.
Code Churn Analysis
Being able to analyze trends and patterns in the commit add and remove history is valuable. Especially if you discover a class or package keeps growing in code complexity. One of the measures for code hotspots was code complexity, which was accounted for by either lines of code (CodeMaat) or number of methods (Code City). Regardless of which one you focus on, if the class keeps growing on a steady basis, it will eventually become a hotspot in the codebase.
The Churn analysis can make a graph of a class’ commit trends and visualize if there is a pattern for when it is growing. Mapping this graph to reality might reveal insight into why this is happening, and how to solve this in the future. Delivery deadlines cut too close, might be what we are actually seeing as spikes in the Churn analysis.
The Social Aspect To Code
It might seem weird to consider the social aspect of software development in a book about codebase analysis through VCS. However, Adam makes some good points about investigating ownership of classes and packages. If you discover the “main developer” on a specific class, it should be acknowledged in the organization. Whenever other developers or teams then must work with or collaborate with the given class or package, it will be valuable to optimize the organization’s communication flow between the main developers of the class and the new team or developer.
Adam goes into further examples and highlight some insights which can be deduced about the organization’s communication flow from the VCS. Essentially, many of the points he presents are based on Conway’s Law:
“Organizations which design systems … are constrained to produce designs which are copies of the communication structures of these organizations.” – M. Conway
The points mentioned above are some of the key takeaways I gained from the book on first reading. I am currently working with CodeScene and trying out all its functionalities. As mentioned earlier, CodeScene has a free plan for small-scale projects. It should be noted that they consider less the 5000 commit a small-scale project. For my case that is all fine. If any of this sounds interesting to you, I suggest that you give it a try, just for the educational purpose. I gain no profit if you decide to subscribe to a plan.
Regarding the book, I am split in terms of my recommendation. On one hand, Adam provides several relevant points of consideration or improvement to apply directly onto your own project. On the other hand, the whole book is based on an outdated version of the new and improved CodeScene platform. If you find the key takeaways, which I presented above, valuable it might be worth giving the book a read to learn more.
Hope that my review of Adam Tornhill’s book “Your Code as a Crime Scene” was helpful to you.
About
Hi, I'm the Author
My name is Daniel H. Jacobsen and I’m a dedicated and highly motivated software developer with a masters engineering degree within the field of ICT.
I have through many years of constantly learning and adapting to new challenges, gained a well-rounded understanding of what it takes to stay up to date with new technologies, tools and utilities.
The purpose of this blog is to share both my learnings and knowledge with other likeminded developers as well as illustrating how these topics can be taught in a different and alternative manner.
If you like the idea of that, I would encourage you to sign up for the newsletter.
Cheers! 🍺
