History Lessons

Those who do not read history are doomed to repeat it

One of the first tasks when studying anything new is to review the existing literature. As a student, I viewed this as a make-work project, but of course that’s not true. Studying the past helps you understand the mistakes and decisions that were made, and it better prepares you for work you’re about to do. The same is true for software development.

When maintaining software, SCM tools such as Git provide developers with extremely powerful tools to study history. It’s easy to look at the history of a file, or all the times when a particular line was modified. Annotations are also a great way to see who changed a file, and more importantly, why.

Studying history is only possible if you properly record it. There are several articles about writing good commit comments, but if you don’t follow all their advice, ensure that each message includes the basics: “Who, What, Where, When, Why and How”. While this may sound like a lot, Git takes care of most of them for you:

• Who, Where and When: These are handled automatically for you by Git. Git will record who authored the work, when it was committed and where in the code the changes occurred.

• How: The nice thing about source code is that it describes exactly how something was implemented. By looking at the additions / deletions, understanding how something was implemented should be trivial. Of course, for complicated code, feel free to add a note to the comment about how this implementation solves the problem.

So your commit message only really needs to explain What and Why.

• What: While code should be self describing, seeing the forest through the trees is not always easy. The reader may need a solid understanding of the entire system to understand what effect this change has on the system. Don’t assume that you’re writing history just for the team you’re working with today. History is for tomorrow.

• Why: The one thing that self describing code rarely describes is why something was implemented and why this particular implementation was chosen. If you do not describe why a decision was made, and someone changes the code to a different, less optimal solution, you only have yourself to blame. If you spent hours, or even days, designing a new feature, take a few minutes and describe what other approaches you considered and why they were rejected in favour of the current one.

Before starting any new code change, take a few minutes and study the history of the related files. When you’re done with a change, take a few minutes to record your findings for the next engineer that comes along. Revision history is one of the most powerful archaeological tools in a developer’s tool belt. Don’t let this knowledge go to waste.

In the next article, we’ll look at some tools for studying history.