In the same way that automation tools don’t replace testing – the advice in this post shouldn’t replace proper reviewing. However, I recently realised that there are a bunch of standard mechanical things that I check for when reviewing, which are fast and easy to check and add good value. I rate them highly as things to do when you’re reviewing – and even better, when you’re creating such items in the first place.
- Eradicate weasel words. Should, probably, negligible, perhaps, mostly, and their friends. These are often hints that whoever wrote this doesn’t know for sure and is kinda hoping it’s going to be ok. It’s absolutely fine when writing a spec/plan/whatever to say you don’t know (or don’t care) what the behavior is going to be in a particular situation. Call it out. Give others a chance to tell you that it does matter to them. Using the weasel words just gives you a chance of sneaking a bug past your reviewers.
- Check the perf section. And the diags section. And the security section. And any other standard template sections that aren’t “function”, and where people can often write try to get away with writing variations upon the theme of “it’ll all be fine”. Often you’ll catch these with the weasel word check above. But also, ask the question, is it actually fine? Really? What about…? Speaking of which…
- Ask why. Skim through and find any unsupported claims about function, about what customer use cases are, about how this will work in the field, about what’s reasonable behavior. And ask why.
- Ask why not. Quickly shove any claims (supported or unsupported) that we don’t need to worry about X, Y, Z under the microscope. Do they hold. Will they hold in the future? Who might care?
Finally, a note on sending the feedback. Be nice. All of the above find issues basically because they’re levering open bits of work where people may not have done all the thinking they needed to. You’re spending very little time and effort, but for the person who’s work you’re reviewing, they may need to spend a lot of hard thinking and time to fix the holes in something they previously hoped was close to done. That can be a little demoralizing, especially if someone sees how little time and effort you spent uncovering that load more work for them.
On the other hand – no need to keep the list above secret. I expect many people who’ve had me review their output to recognise something similar to that list above. Tell people that’s what you’re doing, and they can do those checks themselves (and save both of you time and energy). On that note, if you have any other similar checks that you run yourself that I haven’t mentioned, please share in the comments below. I’d love to improve!