Table of Contents for

Your Code as a Crime Scene

Get Your Investigative Tools

The techniques in this book are based on how you and your team interact with the code. Most of that information is stored within your version-control system. To analyze it, we need some automated tools to mine and process the data, but there aren’t a lot of tools out there we can use.

To get you started, I’ve put together a suite of open-source tools capable of performing the analyses:

• Code Maat: Code Maat is a command-line tool used to mine and analyze data from version-control systems.

• Git: The techniques in this book would work with other types of version-control systems, but we’ll use Git in our examples. You can refer to Code Maat’s web page^[1] to get an overview of mining data from Mercurial and Subversion.

• Python: The techniques don’t depend on you knowing Python. We just include it here because Python is a convenient language for automating repetitive tasks.

Use Git BASH on Windows
	You can run Git in a DOS prompt on Windows. But some of our commands will use special characters, such as backticks. Those characters have a different meaning in DOS. The simplest solution is to interact with Git through its Git BASH shell that emulates a Linux environment.

Forget the Tools

Before we get to the installation of the tools, I want to mention that even though we’ll use Code Maat extensively, this book isn’t about a particular tool. The tools here are prepared for your convenience as a way to put the theories into practice.

While Code Maat does help with the tasks ahead, the important factor here is you—when it comes to software design, there’s no tool that replaces human expertise. What you’ll learn goes beyond any tool; Code Maat just relieves you of repetitive calculations, input parsing, and result generation.

In each of the case studies you’re about to read, the toolset is the least important part. The algorithms in Code Maat are fairly simple—you could implement them as plain scripts in a language of your choice.

That simplicity is a strength. It allows you to focus on the application of the techniques and how to interpret the resulting data. That’s the important part, and that’s what we’ll build on in the book.

After you finish Your Code as a Crime Scene, you’ll be in a position to move beyond Code Maat. There’s even a closing chapter dedicated to that in Chapter 15, ​Toward the Future​.

Install Your Tools

You can get detailed setup instructions for all the tools we’re using from the Code Maat distribution site.^[2]

This book also has its own web page.^[3] Check it out—you’ll find the book forum, where you can talk with other readers and with me. If you find any mistakes, please report them on the errata page.

Know What’s Expected

I’ve applied the techniques in this book on a wide variety of programming languages, including Java, C#, Python, Clojure, C++, and Common Lisp. The techniques are language-independent and will work no matter what technology you use.

Similarly, I’ve used the strategies on both Windows- and Linux-based operating systems. As long as you use a version-control system sensibly, you’ll find value in what you’re about to learn.

We’ll run the tools and scripts from a command prompt. Sure, we could put a GUI on the tools to hide options and details. But I want you to truly understand the techniques we’re discussing so you’ll be able to extend and adapt them for your unique environment. Don’t worry—I’ll walk you through the commands. They’re basic and will work on Windows, Mac, and Linux.

As a convention we’ll use prompt> to indicate an operating system–independent, generic prompt. Whenever you see prompt>, replace it mentally with the prompt for the command line you’re using.

You’ll also see some Python, but we won’t develop in it. We’ll use Python to perform repetitive tasks so that we can focus on the fun stuff. If you haven’t used Python before, it’s fine; I’ll provide the code you need and walk you through the algorithms so you can use them with a different language of your choice.

Tools will come and go; details will change. The intent here is to go deeper and focus on timeless aspects of large-scale software development. (Yes, timeless sounds pretentious. It’s because the techniques are about people and how we function—we humans change at a much more leisurely rate than the technology surrounding us.)

Let’s get started with how forensic psychology helps you investigate your code.