Diffing Files to Avoid Easy Goofs

A good habit learned at my last job has saved me a lot of embarrassment and bugs (same thing): Before committing a set of changes to source control, I look at the diff of each file. Look at the changes, read ’em over, look for misspellings and placeholder notes-to-self and files I hadn’t intended to change; then make fixes and revert as needed. It’s like proofreading. Polishing the fingerprints off a product before sending it into the world. Checking your knot.

Shortcuts for diffing files:

  • In TFS, Shift–double-click a file name in the Pending Changes window. (You can configure TFS’s diff tool.)
  • In TortoiseSvn, double-click a file name in the “Changes made” panel of the Commit window.
  • In git and Hg… help me out here. I’m too used to a visual side-by-side. Recommend a nice explanation of getting the most from those in-line diff reports?

If that seems daunting because there are so many files to review, check in more often. I appreciate the mentors who have drilled into me: small, focused, atomic changes. It keeps me focused on what I’m doing. Make this one change, and every other stray thought that leaps to mind (“Ooh, I need to do this, too!”) gets tossed in a running text file, to be addressed later. How small is small enough? When it no longer feels onerous to diff all your files before checking in. 😉 In addition to keeping my thought process on-track, this habit makes it easy to review, fix, unwind, and selectively pick certain changes when I need to.

Small check-ins are like the extract-method refactoring. In code, when you have a collection of statements that do something, you’d extract them into a method so that you can name the something. Similarly, a focused check-in can have a descriptive and useful check-in comment.

The three habits fit together: small check-ins targeting a focused goal, with a useful commit message, reviewing the changes before checking them in. Reduces the number of times I have to think “Who the heck did—?! Oh, me. Heh.”

Microcontroller Projects and Source Code