It’s nearly midnight. The end of a long coding session. Your code seems to work pretty well; all tests pass and it doesn’t blow up when you use it. It was a hard-fought battle, and you’re feeling great! The only reason it’s not already in the product is because your team has fostered a culture around code review.
At this point, you may be feeling ready to just post your code for review and move on to something else, waiting for the feedback to roll in. Is that what you do? Well, stop it! You’re only making things harder for yourself.
Your first reviewer should never be another person. It should be you!
Self-review saves time and increases quality
A typical code review cycle can easily take anywhere from an hour to a couple days. If your code isn’t perfect and your team is thorough, you will go through at least one cycle with at least one developer.
Likely more, since developers are often distracted by the tiny problems (style issues, typos) and ignore the larger problems (algorithmic issues, design flaws, bigger picture tasks) when reviewing. Oh they’ll get to the larger ones, but it might take another full review cycle or two.
Self-review can save you at least one cycle. Maybe more. The other reviewers will get to spend more time focusing on the more interesting issues instead of the little flaws, making them more likely to want to review the code. Plus, it’s far easier to convince people to look at your code when they think they’ll get through it quickly.
Let’s summarize the benefits:
- Your code lands faster.
- The feedback is more useful.
- People will think you’re awesome for not wasting their time and will bake you cookies as thanks. Probably.
Now let’s talk about how to do self-review well.
ProTips for self-review
You may be used to reviewing other people’s code, but it’s going to be a bit different reviewing your own. You’ve already built up a mental state of how your code works, and won’t be reading it for the first time. You’ll have a bit of a blind spot that other reviewers won’t have, making it more difficult to see the flaws.
You can do something about that. Here are a few tricks we’ve learned.
- Review your code in your code review tool, not your editor.
This will help put your brain in review mode, and take you away from your editing environment. This little context switch can be enough to help catch problems you wouldn’t have seen before.
- Wait to post the code for review.
If there’s no rush to land the code, wait a day, work on something else, and then come back to it. You’ll have paged some of it out of your head by then. You might be surprised by what you notice.
- Re-learn, don’t remember, how your code works.
Pretend you’ve never seen your code before. Read the code line-by-line, character-by-character. Don’t make any assumptions. You may catch some confusing variable names, documentation, or bad logic this way.
- Use checklists for code review.
Keep a checklist of problems to look out for. Your team’s style preferences, possible edge cases, possible memory leaks, exception handling… Anything you can think of that may apply to your changes, or that of your team’s. This will help take a load off your sleep-deprived brain.
- Read documentation, comments, and displayed text out loud.
You should read through every error message, every piece of documentation, and every comment out loud. See if it makes as much sense as you thought when you wrote it. If it helps, try explaining it to a rubber duck.
- Take the opportunity to write more documentation.
If your code is low on documentation/comments, this is a good time to write some. Go into detail, cover corner cases, or anything that may be valuable to another reviewer.
By being forced to write about your own code as you read it, you’ll not only help ensure your code does what you expect, but you’ll help other reviewers get through a review cycle much faster.
This also works pretty well for unit tests.
These are a few of our tips we use when reviewing our own changes. What are yours?
5 thoughts on “Practicing effective self-review”
Review code with a different tool than you write it…so simple, so brilliant. Becoming part of my workflow immediately.
I found that new hires often just don’t think to read their code in the code review tool, I always explicitly ask for it now. It really help catching mistakes if you see your code in the same tool as your reviewer. You don’t want to waste your reviewer’s time with simple formatting or spelling mistakes while they could be looking at more important things.
I agree with the general recommendation of this article that it helps to review your own code before passing it on to someone else to review and I find it helpful to look at it in the same tool the other guy will be reviewing it in.
But the rest of the recommendation seem to come from a fairy-tale world to me:
In reality, who has the time to “wait a day” before re-reading the code? (Imagine there’s no deadlines, and no clients, too. Imagine all the coders…)
“Pretend you’ve never seen your code before” – how do you do that? Bang your head against the wall really hard and hope to induce amnesia?
“Use checklists for code review” – and if you do, keep it to yourself because the next thing you know, it becomes the company policy, there’s a half-broken web tool your company requires you to use which randomly breaks other web tools it pretends to integrate with.
“Read documentation, comments, and displayed text out loud” – in an openspace, right. That calls for a Monty Python sketch.
“Take the opportunity to write more documentation.” – implying you have a lot of spare time and energy left after you have read your entire code submission out loud in the restroom to the accompaniment of your colleagues banging on the door to make you get the *#@! out of there.
But as I’ve said, I agree: let’s keep dreaming!
P.S. Don’t take this comment too seriously. It probably just means I need a vacation.
Self review is less biased when done not immediatly after producing the thing. “Wait at least 3 days” may be a tip for effective self review.