Check in your Changes

At work, managing changes in files is a big part of what I do. These files are put together to make up a design unit. Many design units are put together to make a whole SOC. Much of the data is constantly evolving.  Files might be changed by myself in my current workspace or by someone else and committed to the server ahead of me. All these changes have to happen cohesively to keep development moving forward.

As an individual contributor, part of my job is not just making changes but also managing and understanding how files are changing in the design as a whole. Importantly, when I change a file and get set to check it in I need to be sure the changes are correct. If that seems obvious, it is. But truly "correct" goes beyond just running a test suite. I typically check:

• are the comments still correct
• are there any debug print statements that need to be deleted
• are there any temporary experimental changes still hanging around
• are any files changed unexpectedly
• are my files too old to commit

After checking the status of every file to make sure there are no unexpected changes, my I perform a diff of every file. I use a graphical tool, tkdiff. Sometimes the differences are so numeras that the task seems daunting:


That picture represents 67 changes across almost 800 lines of code. Going through this change by line by line takes 15-20 minutes. The cleanup is worth it. Code that is checked in after this type of last minute read-through goes a long way towards keeping the code the best it can be - outside the domain of pure functionality.

By using tkdiff, I can scroll round up and down from each change. This lets me look at the comments - especially the ones that have not changed next to code that has changed. This is how I keep comments correct.

That last bullet, "are my files too old.." is very important. In this case, when the commit is run one of too things might happen. One, the commit goes through. Or two, the version control tool reports that I can't commit because my changed file is out of data with respect to the server. Two may seem unfortunate, but it is actually better than the first one which can introduce errors later. In the second case, I'm forced to update, and re-run the test suite. Why isn't it OK to just check in when I know my workspace contains a lot of stale (files that have been changed on the server)? Because after I commit my changes the state of the server data is not known - it hasn't been tested yet. It could easily fail the test suite.

What to do about a workspace that is out of date depends on the data that is out of date. If it is related to your change, you really should update your workspace and re-test. If it isn't it might be safe to simply commit the change. But beware, it is always better for your group (your colleagues who will soon see all of your changes!) to check your work first. So finish your changes, then merge with the latest data on the trunk, turn the test suite and deal with any issues yourself. This saves the team valuable time. One way to do this is to "merge early and often." If you never let your workspace get stale, you won't have this issue.

If you can convince everyone on your team the importance of merging early and often. To only run the test suit on data that is as close to HEAD of the tree as possible. You'll find the group will save time by spending less of it sorting things out with those annoying reply-to-all "who checked in xyz and broke everything" emails.

Of course none of this replaces keeping yourself from going dark. There is also the need for periodic peer reviews.

So, how do you manage your check in process?