Channels ▼

Pablo Santos

Dr. Dobb's Bloggers

Self documented development through inch-pebble checkins

April 30, 2009

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.

Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 


Video