Multitasking is good for processors but bad for people. Each interruption breaks concentration and flow. Each context switch is an interruption. According to Tom DeMarco and Timothy Lister’s classic book Peopleware, it can take up to 15 minutes to get back into the flow after an interruption. As a programmer, how much work do you get done when you’re constantly interrupted? How many interruptions until your workday is fragmented into tiny pieces of frustration?
Maybe it’s not even others interrupting you– maybe it’s the code itself. You look for something in some part of the code and notice an odd method. Should that still be here or is it dead code? You skim some function body and wonder if it covers a special corner case that comes to mind. While programming, we keep many details in our heads. How can you not lose all those details? How can you keep in the flow, and at the same time not forget about what just caught your attention?
Get a good-ole to-do list! Leave yourself notes, but not on paper– that would be a medium switch, and even looking for pen and paper may disrupt your flow. On top of that, you may lose notes on paper or forget about them. What use is the note if you don’t come back to address it? Preferably you’ll want to check your notes before you commit your changes and/or decide if the notes merit a separate commit.
Here’s where DONTCOMMIT comes in. Just put a comment in the code, mark it with DONTCOMMIT, and leave yourself enough explanation on what you wanted to do here. For example:
// DONTCOMMIT do we still need this?
// DONTCOMMIT doesn’t seem to handle -1
Then go back to what you were doing, without breaking flow or concentration. It’s like the TODO and FIXME items you probably already have, only better.
These special DONTCOMMIT comments stand out in the code. If you happen to have DONTCOMMIT somewhere else in your code, feel free to pick something else. You now have a unique marker for these notes. You can grep for that marker in the shell. Your IDE can probably be configured to highlight and show the markers as todo items. For example, in Eclipse, go to Preferences and search for “todo”. You’ll find it in Java -> Compiler -> Task Tags, where you can define your new tag. Once that is done, Eclipse will put a blue marker on the right-hand side of that line, and a little icon on the left. Your new tag will also show up in the Tasks list (Window -> Show View -> Tasks).
IDE is nice, but it’s still easy to forget those DONTCOMMIT items. Luckily, version control systems support hook scripts, so you can register a hook script that looks for your marker (e.g., with grep ) and rejects the commit if it finds the marker. Automatic reminders!
For example, in Subversion you’d place a script like the following in your repository’s hooks/ and call it from hooks/pre-commit or just put the following in hooks/pre-commit (and make it executable):
#!/bin/bash REPOS="$1" TXN="$2" set -u while read file do for bad in "DONTCOMMIT" do found=$(svnlook diff --transaction "$TXN" "$file" | grep "$bad") if [ -n "$found" ] then echo "Found $bad in $file:" >&2 echo "$found" >&2 exit 1 fi done done < <(svnlook changed --transaction "$TXN" "$REPOS" | cut -c 4-) exit 0
For git, the hook scripts go in .git/hooks/pre-commit and look like this:
#!/bin/bash set -u while read file do for bad in "DONTCOMMIT" do found=$(git diff --staged "$file" | grep "$bad") if [ -n "$found" ] then echo "$bad found in $file:" >&2 echo "$found" >&2 exit 1 fi done done < <(git diff --staged --name-only) exit 0
While your hook is already looking for DONTCOMMIT, have it do more! You should also check for DONTCOMIT, DONT_COMMIT or any other “creative” spellings. If you want to take a quick note you shouldn’t be bothered to get the tag name exactly right. Keep in the flow, let the hook script take care of it by adding your favorite spelling errors.
Another idea is to flag your username so that you don’t check in hardcoded paths that only work on your machine. Reject System.err.println, printStacktrace, and other forgotten printf debugger statements. Reject any // IDE generated stub, and so on.
Mark your code, keep in the flow and let your version control system do the grunt work for you.