Stories of Your Code
Foreword to Your Code as a Crime Scene by Adam Tornhill
Your codebase is overflowing with stories.
There are, of course, the narratives of control and data that flow through each function, threading blocks and objects together to build an application’s behavior, which itself reflects the user stories that shape the development timeline.
There are the personal stories that accompany each individual connected to the software, whether developer or manager, architect or customer. These are the successes, frustrations, weddings, children, delights, losses, fashions, ups and downs of well-being, and all those things we call life that make up the backdrop against which code is written, heads are scratched, whiteboard discussions are had, bugs are fixed, and logs are puzzled over. For those involved in the creation of software, the stories of the code and the stories outside the code are woven together. Software development is made of people.
From the perspective of a compiler, code is a technical construct, one formal notation to be translated into another so that it can run. The compiler’s view is simple and certain: just as with ones and zeroes, code compiles or it doesn’t. From the perspective of an organization, however, code’s complexity is drawn in shades of gray. Software is a socio-technical construct, where team dynamics, deadlines, personal preferences, skills, and organizational values leave their mark on a codebase and its history.
And this is the perspective Adam takes in this book. The new edition of Your Code as a Crime Scene retains the soul and wisdom of the first edition, while updating its examples and extending its reach. Adam shows us that to truly understand a codebase, we cannot simply view it through the keyhole of our editor in the moment of editing. We need a larger and more holistic view, one that invites novel ways of thinking about and visualizing code. This is the journey Adam takes us on. But this is not code tourism: Adam offers us the context, details, and insights that will grant us local knowledge.
Our source code has a spatial structure — top to bottom, left to right, indented and aligned — but we can invent and use spatial metaphors to further enrich our mental models and reveal the shape of our system — cities, graphs, maps, enclosures, fractals, and more. And where there is space, there is also time. To gain a deeper understanding of our code and its development, we need to learn to see it as temporal not just spatial. There is a story that led to the code we see today; there are stories that may flow from it in future. A system is no more a static snapshot of its code than a film is a single frame. Adam shows that, buried within your version-control system, you have more than a repository: you have a history. Buried in the commits and the diffs is a story of what changed and when, who made changes and why. This is where you will find the system.
Among the hotspots and dead spots, trends and coupling, you can find connections to requirements, to technical debt, to team structure, to project practices, to defects, to technology evolution, to programming paradigms, to organizational change, and more. With the forensic tools and mindset Adam presents, you can see what’s happened and what’s happening and, therefore, what might happen and how you and others can change that.
The story of a system is not just yours to discover; it is also yours to tell.
