I’ve recently been digging into code review and wondering how to do it well. Over the past few years, I’ve had mixed experiences with code reviews; sometimes they seem to help so much, other times not at all. There’s a lot of writing out there about the value of code review, but not so much on the details of how to do it.
How can we improve our code reviews? Here are four rules that have helped me.
1) Read the Code
2) Think before you speak
3) Ask questions instead of spotting bugs
4) Help everyone learn
Here are the four rules I try to follow when reviewing code. These rules are simple enough to fit on a pencil. They help me find and fix bugs, which makes me a better engineer. They might help you too.
Rule 1: You’re not going to read it
A good programmer will eventually understand all the code in the program. But for now, you don’t need to.
Rule 2: You only have one job
Your job is to find bugs and suggest fixes. That’s it. Don’t tell people how to do their job, or what would make them happy, or what is good code. Just focus on finding bugs and suggesting fixes for them.
Rule 3: Read between the lines
The most important thing you can do is understand what the person who wrote the code was thinking when they wrote it. This helps you figure out how they were planning to use the code, and where they might have made mistakes in that plan. Why? Because understanding why someone did something will help you figure out whether they did it right, or whether they made a mistake instead of doing it right. Their intentions are more important than their actions, so read between the lines to figure out what they intended to do instead of what they actually did do.
I’ve been using Git for over five years, and I’ve made some mistakes. I wrote about how I learned to stop worrying and love git commit –amend earlier this year.
In the past year or so, I’ve been working in a team that regularly reviews code with pull requests. This is a new experience for me. In my previous job, we had one developer who was the de facto gatekeeper of our codebase – he reviewed everything before it went in (and he did it very quickly). Now, as a junior engineer at a small company, I get to review other people’s code.
I like reviewing code because you get to see how other people work, and you get to learn from their ideas even if they are not merged into the project.
Reviewing code can be difficult and frustrating, but it is an important skill to get better at. Here are four tips to make your life easier when reviewing code:
When I was a new engineer, I loved code review. I would spend hours making sure my code was perfect: no bugs, the most efficient algorithm, cleanly formatted and commented, and documented. I would then spend an hour or so writing a diff comment that explained what I did, why I did it, and where I thought things could be improved.
My reviewers would then spend all of ten minutes reviewing my changes and say “LGTM” (looks good to me).
Code review is great for catching bugs and stylistic issues in your code; however, it’s not great at teaching you how to write good software.
Here are 4 rules that have helped me tremendously in writing better software:
At the start of 2014 I decided to do two things:
Find a new job.
Code every day.
Despite having worked as a software engineer for 7 years, I had never kept a code journal. A code journal is where you just keep track of what you did. It’s often trivial and even tedious since you’re logging your every move as a programmer. It’s like keeping a diary but less personal.
I started my code journal on January 1, 2014 and it was so helpful that I continued writing in it daily until the day I left my previous employer. I wrote this blog post to explain why anyone who writes any amount of code should maintain a code journal, and how to make one effective.
Why Keep a Code Journal?
Keeping a code journal is largely beneficial to your future self, but there are other benefits as well.
A Record of Your Mistakes
The most valuable benefit is that you can look back at your mistakes so that you don’t make them again in the future. This especially applies when you have multiple repositories or projects with similar setups and configurations. Having your notes from previous setups will save you time when creating new ones because you’ll know what works and what doesn’t by reading your own notes!
When I was a kid, I wanted to be a programmer. I played with computers a lot: my parents had bought me a Commodore 64 when they decided they couldn’t afford to send me to private school anymore. But at some point I realized that I was never going to be great at programming; the best programmers are the people who can hold many different ideas in their head at once and move between them smoothly, and that’s not something I’m good at. There is one exception: I have always been better than average at reading other people’s code.
I blame my mom for this. When I was little, she taught me how to read by reading chapter books aloud to me every night before bed. This made me unusually good at reading later on. Reading was something you did for fun, not work; we didn’t have a television, so it was about the only entertainment available. And my mom had an odd habit of reading out loud even when there was no one around to hear her. So I got plenty of practice listening to people read; and by the time I started school, my habit of reading was well enough established that it never occurred to me to do otherwise when confronted with writing
If you have worked in any kind of software development organization you probably