My check-in procedure

A few weeks ago we had a discussion a forum discussion. Question was - what tips did we have for junior developers (not only programmers, all specialties). My #1 tip was: always diff before checking in your changes! I still stand by it, but thought I’d elaborate a little bit and give a quick overview of how I handle my commits these days. Not a rocket science for sure, but the presentation (and hints) were aimed at people just starting in the industry.

When first creating a changelist I only give it a short, “internal” description, just for me. The proper, final description comes later, just before checking it in, once all the changes have been finalized. I like to do it in 2 steps:

• diff all files that I’ve checked out (against the repository), in P4 it’s “select all+diff”
  
• go through all the changes, make sure there’s no debugging/temporary/weird code there and they all make sense
• write a short ‘story’ based on the changes you’re inspecting. Explain what changes have been made and why. Point out the consequences/limitations if necessary. Not every tiny modification warrants a mention, but it’s probably better to err on the side of too much information.

Following these simple guidelines makes sure that you only check in what actually needs to be checked in and has a nice side-effect of providing a detailed description so that anyone reading in later can not only see what has been done but also gets a quick overview of how it’s been done (obviously, this is still a very high-level overview, but can be a life-saver especially if trying to find a problem later).