Trigger Checklists!

I love checklists. I have a terrible memory, so it’s very easy for me to forget all the things I need to do. If I go to the store without a list of things to buy, I will forget at least one. Or two. Or I’ll get the wrong type.

I do the same thing with software. If I don’t have something reminding me, I’ll forget to check all the getters I’m using to see if they sometimes return NULL. I’ll forget to check that my new member variables have been added to all the initialization list, the comparators, AND the hash function. So this is why I love checklists: because they remind me. They help me catch the simple errors that I can catch easily if only I pay attention. And they give me some degree of assurance, the third time I should have asked how a function should behave on empty inputs, that I’m not going to make the same mistake again any time soon, because I’ve added it to my checklist. I review my checklists regularly to remove extraneous or not-effective parts and keep them a reasonable size (less than a dozen items), and in general, the upkeep of the lists is no problem.

My problem with checklists is that I often don’t remember to use them.

I’m not alone; we started using a code review checklist a few iterations into our practicum project, but we kept running into very same the issues it advised us to check. It wasn’t until we decided that the reviewer should have a printed copy of the checklist with them and check off each item whenever they did a code review that we started to see its benefit. Our original problem was that we had never decided when to use it.

This same problem is what has been affecting my personal review checklists. I realized: It’s just as important to describe when to use the checklist as to describe what things to check.

The obvious extrapolation for my personal reviews is to say, “use the code review checklist before compiling or submitting,” but I realized that I could get feedback much more quickly by breaking up my list into smaller, easier to apply pieces. I call them trigger checklists. Here’s one of mine:

Are you adding a method?

  • What if the inputs (or even class members) are null?
  • Can the method be const? Can the inputs be const?
  • Is there a JavaDoc style comment?
  • If the method is used in another toolkit, is it exported?

So far, this has been great. I have my trigger checklists on a sheet of paper next to my monitors, so I’ll glance at it fairly often in a day. If I’m in the middle of doing one of the things that trigger a checklist, I’ll go through and check each item to make sure I’ve covered my bases, or add TODOs to help me remember to check specific things later.

"Soon, our missiles will launch and the world leaders will - wait..." *checks a list titled, "Revealing your secret plan to an enemy? Are they dead? are you sure? etc... "Haha! Good try, good try.

PS: I went on a search online to find some good checklists to link from here, but there aren’t many, possibly because each checklist is so tied to the team, domain, language, and libraries. Macadmian has one which is good, if long and for team code reviews (I suspect that team checklists will often be longer than personal ones). If you have a copy of A Discipline for Software Engineering, Humphrey’s C++ checklist for PSP is also good (it’s on page 242).

Thanks to Geoff Geisel for looking over a draft of this and for his feedback. Geoff was part of our practicum project.

This entry was posted in The Craft and tagged , , , . Bookmark the permalink. Both comments and trackbacks are currently closed.

One Comment

  1. Posted March 18, 2010 at 9:22 pm | Permalink

    Nice! I think checklists are very specific to teams, if not individuals. I can see myself reminding people to ‘build before copying code to production’ and ‘run test before deploying’. Probably I should make these into a big poster and put them where people can see.