Revision Control System Ettiquette

Develop software for any length of time, and you will reach the conclusion that being able to track changes you make to source code is "a good thing". Put a show-stopping or embarrassing bug in the last round of code changes you made? Being able to revert to an older version of the source code, may be the fastest way out of your problem! If it isn't, it may at least help you to understand what you did wrong – by comparing different versions of the source. This isn't rocket science – software development teams have had Revision Control Systems (RCS) to help them do just this for a long time.

If you work as a programmer and you have never heard of RCS, then I suggest you see this thoroughly excellent visual explanation of what one is. Then explain to your boss, that you need one. Those of you who are more in the know, will realise that the introduction I linked to is a few years old, and doesn't attempt to explain what a Distributed Revision Control System is, but for the purpose of this article, it is satisfactory.

Working collaboratively on a project more-or-less makes using some sort of RCS mandatory. Sure – you can survive without it, but it simply makes no sense to do so. One of the highlights of using an RCS is the ability to show how source code evolves. Being able to diff the revisions of the code can be useful to help fellow team members understand how the code came to be the way that it is.

Just because you can see what differences there are in two versions of the file, doesn't mean you will understand what the differences are! It is easily possible to change code sufficiently to make following your changes close to impossible. Even if you are developing in isolation, you should be using an RCS and acting as though someone else will be the next person to work on your code. This is especially important, just in case you are the next person to work on your code! :)

Here are some simple guidelines to try and follow when checking in code changes:

  • Only attempt one change per check-in. If you have several bugs to fix that all relate to the one piece of code, it is tempting to fix them all at the same time. This is discourteous to anyone attempting to understand your changes at a later date.
  • Explain what you are doing. When committing a change to the RCS, you get the opportunity to submit a "check-in comment". In much the same manner as commenting code, these are best used to describe the intent of your revision. Normally, people use the comment field to provide a reference back to a bug-tracking number. This is worthwhile, but it falls short of being a great check-in comment. I am sure that the vast majority of coders can type quickly enough that expanding their check-in comments won't take them too long!
  • Code styling / formatting gets its own check-in. So, you didn't like the order someone put the class methods. Or, they didn't put spaces between function parameters the way it is meant to be. You feel moved enough to change it yourself. Well, just check it in separately. Again, this goes back to being courteous to someone who may be trying to follow your changes at a later date. Logic changes can easily be buried / hidden by moving the function they occur in. The diff output will show that a function was removed from a certain point in the file and inserted somewhere else. Subtle changes in the function can easily be lost

All of the above recommendations are aimed at improving the accountability of the code changes you are making. This becomes more apparent when you are working on a team that uses code reviews as part of their development methodology. The relative-worth of code reviews can receive fairly heated debate, but that is a story for another time.