Self documented development through inch-pebble checkins
“Nothing can be quite so helpful as well-placed comment.” This the first sentece in the chapter 4 of Clean Code wrote by Robert C Martin.
There are good comments: when you find a weird bug or need to understand why a certain change was done, then you wish you had proper documentation. And, indeed, there are bad comments. Let explain yourself in code to avoid writing comments in bad code.
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: software change
Software is not a product, and software development is going to adapt to resolve the requirements about the domain problem. There is a rule about of Software Change: “Embrace change to control change”. The more flexible and adaptive you are at accommodating change, the more control you will have over it.
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.
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.
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. This way every changeset will help understanding what I did, step by step.
I'm using a branch to hold all this changes.
So I started:
- I moved a private method from the top of the class to the bottom (privates should always go at the end) → I created a changeset describing this change
- I moved some code from the old class to a new one containing new code → I created a new changeset containing only this change
- I created a new method to handle part of the new functionality → another changeset.
And so on 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.
How Plastic SCM makes all this working process?
First we create a new branch and switch workspace to this branch.
Figure 1: New branch
Then I start to work. All my changes will be in this branch and I can commit as many times as I want. Using the Changeset View on Plastic SCM, we can follow all the updates made in the branch.
Figure 2: Changeset View
Figure 3: Pending Changes View
At the end of the day, the original file I started working on (I won’t include the new ones) had the following history:
Figure 4: Branch History (Inch-Pebble)
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.
Figure 5: Plastic SCM -- Branch Selected
Figure 6: Contextual Menu View
Contextual Menu View, has three options:
- View Changeset on this Branch
- Explore Changeset on this Branch
- Browse Repository on this Branch
Selecting Explore Changeset on this Branch, like in the following picture.
Figure 7: Explore Changeset in Branch (Plastic SCM GUI)
Each changeset contains a set of modified files plus a hopefully meaningful comment. With the right tools you can easily and graphically inspect each changeset content in such a way you’ll be following the steps of the developers as if he was wearing some sort of code camera.
Figure 8: Explore Each Changeset in Branch
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.
0 comentarios: