Developers hate writing documentation. But when you find a weird bug or need to understand why a certain change was done, then you wish you had proper documentation. The problem seems hard to solve. Good comments can help and techniques like diff debugging and proper code review tools can help too. But what every developer does on a regular basis is checking in code to his repository. What if the way in which you check in could help self documenting the code?

Side note: I find the technique I describe here not only good for self documenting changes but also to capture the way in which lead programmers work in such a way it can be used to teach the newcomers...

The problem: code that changed too much

We use branch per task pattern internally and we enforce reviewing changes done on branches as a prior step to integration (merging). But sometimes code changes too much and running a diff doesn't seem to help us much as it does when the modification is small. Let me explain why:

A couple of weeks ago I was developing a new functionality which required making some changes on a existing source file and adding other two new ones. Since the new functionality was going to share a good part of the code with the existing one, most of my work was doing a refactor to correctly place common code.

When I finished the change I run a diff on the previously existing source file, showing all the changes I did, which is what a code reviewer could easily do as soon as my branch was marked as finished.

 

Look at the diff tool scrollbar on the right: it shows a ton of changes, so it's not going to be easy to check what really changed and what did not, or what exactly I did based on the diff.

Inch-pebble checkins

Inch-pebble is a term used in software engineering to describe mini milestones as Johanna Rothman describes here.

I'm borrowing the term to describe a process in which you check-in code very often to your SCM and always containing really small and easy to understand changes (hence code inch-pebbles).

What I decide to do on my task was to describe my changes, but instead of using some sort of log file, I checked in code every time I changed a few lines of code. This way every changeset (you know any modern version control will logically group all the files you check-in together, and each of this logical groups will be known as a changeset, a commit or a transaction depending on your SCM's jargon) will help understanding what I did, step by step.

I moved a private method from the top of the class to the bottom (privates should always go at the end), so I created a changeset describing this change. I moved some code from the old class to a new one containing new code, so I created a new changeset containing only this change. I created a new method to handle part of the new functionality, another changeset. And I continued until the code was finished.

Remember I'm using a branch to hold all this changes, so I'm free to commit as often as I want, and I don't have to worry about breaking the build or the trunk. My purpose was creating a sequence of well documented changes so that someone could follow and understand my changes later on, step by step. Somehow, I'm recording a movie of my way of working, frame by frame. It's easier to understand a refactor step by step than looking at the whole process once it's finished.

I think this can be applied not only to refactors, but also for new functionalities, and if correctly done, it could be used to capture the way of working so that not only the results but the process itself gets recorded on the version control tool, storing very important information that could be reused by other developers to understand how things get done around here.

At the end of the day, the original file I started working on (I won't include the new ones) had the following history:

 

Reviewing changes, watching the changeset movie

Since I was checking in so often, I created a set of changesets that can be reviewed, step by step.

 

Each cset contains a set of modified files plus a hopefully meaningful comment. With the right tools you can easily and graphically inspect each cset content in such a way you'll be following the steps of the developers as if he was wearing some sort of code camera.

 

Conclusion

What I described is not new but I thought it can be helpful to support the check-in early, check-in often rule of thumb. It's not only good to work on small and hopefully tested steps, but also to self document your changes in such a way someone can understand the reason why a certain change was made and whether it is right or wrong, something extremely important once a project gets bigger than a few thousand lines of code.

SCM tools can help a little bit more playing changeset movies, creating a new and more effective way to run code reviews.