This blog has dedicated itself to the intricacies of code reviews. We’ve written about best practices, our review-centric philosophy for development, the case for simpler code reviews, and a few more topics of interest. We haven’t, however, taken the time to explain what code reviews are to the non-developers. Now is that time.
Think of a book.
Do you have one next to you? Do you know how it was made? Let us tell you about editing a book. When we’re done, you’ll know exactly what a code review is.
1. The author creates a draft
You can’t have a book without a writer, much in the same way that you can’t have code without a developer. The book can be of any kind. It can be a novel, it can be a collection of short stories, or even non-fiction and essays.
No matter how gifted the author, they can always use the help of a publisher to print and sell the book, but also an editor to work on the text.
Regardless, it’s up to the writer to produce a draft before they come in. It doesn’t need to be a finished book, by the way. For many publishers, the editor (sometimes two or more) will work right alongside the author throughout the writing process.
Developing code is similar. The developer creates the code and the reviewer looks it over for inconsistencies, problems, mistakes… Anything, really.
This is how we see things:
- Author – Developer;
- Book – Feature/task the developer is writing code for;
- Editor – Reviewer assigned to this feature/task;
- Publisher – The company or team.
2. The author edits their own work
“Editing is writing” is an old creative writing slogan that rings quite true. Any author worth their salt will never dump their uncorrected first draft on an editor. They will always go back to work, retrace their footsteps and improve what they’ve done. Ideally, the author will be able to answer any questions the editor asks about their work, and the choices they made.
In code reviews, every developer should be their own first reviewer, always checking their code while the decisions made are still fresh, so the reviewer will have as easy a task as possible.
3. The author will hand off the draft
When the author is happy with their work, they will then send it off into the wild. The wild, in this case, is an editor. This is a relationship that is sometimes described as adversarial, with both authors and editors feeling like they should have the last word over the text, because they are, in their own ways, specialists. This is, of course, pure nonsense. It’s in fact an exercise of co-ownership, where both parties profit from the text being of the highest quality.
One of the hangups people have about code reviews is quite similar to this. Developers, like authors, are fearful of the critiques and suggestions that reviewers and editors send their way, and they feel exposed when their work is in the hands of others.
There’s no need for this. Reviewing, much like editing, should be about collaboration, not confrontation.
4. The editor will fix mistakes, but, above all, they will make suggestions
The editor is a second pair of eyes. The author is living inside the world of their writing, which many times is a little too close to see the bigger picture. Someone else that comes in fresh, and is encountering the text for the first time, will be able to see elements that are missing and things that aren’t doing their job properly.
A reviewer will do the same thing for a codebase. They will find mistakes, of course, but the most important part of the job is to look at the code and try to understand it. To ask questions and make suggestions. The goal is to elevate the work.
5. The draft goes right back to the author
This is a moment of great anxiety. The work you put so much into is coming back with gasp criticism. Comments. Suggestions. It’s wrong, it’s all wrong. It’s terrible. You are a fraud.
No.
Of course not. If the editor is good at their job, and sensitive to the idea that the author is another human being who’s doing their best, the comments and suggestions should be light-weight, thoughtful, and humane. Whenever there’s an issue that is a little more complicated to follow, authors are encouraged to get in touch with their editors to discuss them and come up with a joint solution.
There is no difference for code reviews here. The reviewer and the developer will ideally engage in creative dialogues that will produce solutions that neither of the two could’ve come up with alone.
6. Time to make changes
Sometimes changes are small, and the first draft only gets slightly altered. Sometimes the editor will find a serious problem that needs a complete rewrite. Most of the time, the result is somewhere in between. The author will select which comments and suggestions to disregard and which to pursue. Some text will be rewritten, some mistakes will simply be fixed.
In code reviews, the developer will go through the same process. Not all suggestions need to be handled right away (or ever), and the reviewer isn’t the final authority. The suggestions and comments will bring forth new ideas and, ideally, result in a better code.
7. Do it again
The editing process only culminates when the book is ready to be printed. Until that printing press starts whirring, changes can and will be made. Other people will be proofreading the book as well, not just the original two. Most books will be read by assistant editors and proofreaders as well somewhere along the process, to ensure that as many issues as possible are ironed out.
Code reviews should be a continuous process as well. As long as the developers are making significant changes to the code, it should be getting reviewed as well. Other reviewers should definitely come in as well, allowing for collective ownership of the codebase.
8. Never be satisfied
What if the book is printed and you find a mistake? What if you want to update the book with more recent findings? What if you decide the story needs to be expanded? That’s what second, third, etc. printings are for. As long as the book is on the market, edits can and will happen. Expanded editions will be published. Revised editions as well.
That is the life of software development too. Software needs to be maintained and updated. Much more so than books.
And where there’s development, there should be reviews.
Let us know what software development topic you would like to see “for dummies” next!
Top comments (0)