Small frequent changes

When I first started using version control software (originally SourceSafe, now Perforce), I used to have a large amount of changes over many files checked out all at once, which I would work on over a week or more and then check in at once.  As I have become more experienced I have started to favor many small stable check ins containing a few hours to couple of days of work to large monolithic check ins which represent a week or mores work.  The reason for this is that I’ve had to support at various times software I did not write, which means I don’t know the full history of the source code and there is usually no documentation or original authors to quiz either.  Software in this state forces the maintenance programmer to relay only the only two remaining sources of information available the source code itself and the version control history of each file in the project.

Having to relay on version control history of files for investigating bugs highlights just how much of a bad idea large monolithic check ins are, especially those with short check in notes and lots of changes.  The problem with large check ins is simply that the check in contains many different changes for potentially many different tasks e.g. bug fixes, new features, refactoring.  Which makes it much harder to quickly and easily see the changes for the particular task you are interested in.  This problem can be exasperated by refactoring being combined with other work in a single check in as it makes it even harder to separate the refactoring from the bug fixes or new features.

I have also become much more picky about the descriptions entered in the version control software for each  checked in file, I used to be brief but now I find myself being more detailed in my description of the work contained in each check in.  I find that doing software maintenance, especially on systems where all the original authors are no longer available, really presses home the need for descriptive check in notes.   As without a detailed note of what each check in contains the poor maintenance programmer is forced to sift through every revision of every file in a project when looking for a bug, which only has to be experienced once to make even the most terse note writer a believer in descriptive check in notes!

I’ve also found myself developing the habit of checking in the skeletons of new programs as I write them for example I will create the build, configuration and source files for my application and then get these files building and then check them into source control.  This lets me easily see the differences when I start working on the first feature, as otherwise all the files would appear new in version control which would limit the effectiveness of the source control & comparison tool combo as a means to detect changes.

Code reviews have also highlighted how not checking in the application skeleton can make it much harder on reviewers who now need to work out which changes are just program structure related and which are feature related.  The most unpleasant code reviews are those of whole programs that have been developed from scratch to fully functional without a check in.  It is unrealistic and unfair to expect a  worthwhile or comprehensive review of such a check in, unless the application is a tiny single source program of under a couple hunderd lines or less, as the review will simply be swamped by the sheer volume of the changes.

Part of my passion for source control is driven by my love of file comparison tools like Beyond Compare, which allow the visual display and highlighting of the differences between many types of file.  File comparison tools ares especially useful when viewing the history of a file in version control, when hunting for bugs, remembering and reviewing what you’ve changed and performing code reviews.  One of the first things I will do when setting up a new workstation is to install Beyond Compare and set it up as my default file comparison tool in Perforce.  I will regularly diff files with Beyond compare over the course of a day: to review my work so far, to review work before I submit a code review, to check a files history, to verify program output versus expected output etc…

In my mind the ideal check in:

• Contains only changes related to one type of task: skeleton source code, refactoring, bug fixing or a new feature.
• Has a detailed note attached: anyone who submits ‘updated’ as a note should be challenged.
• Represents a short peroid of work e.g. an hour up to a couple of days.
• Contains no unchanged files: this is a personal bug bear, nothing clutters up file histories like check ins of files with no changes.  If possible disable this on the source control server or client.
• All files should be manually checked with a comparison tool, to check for test code, unessessary changes and temporary hacks.
• Should NEVER break the contineous auto build.
• Is fully tested using all available testing resources.
• Has be code reviewed by a peer.