Top tips for better code reviews

Posted by s.aragon on 21 May 2022 - 9:00am
Black and white typewriiter
Photo by Markus Winkler on Unsplash

By Thibault Lestang

Code review is known to be an effective way to improve software quality, foster peer learning and develop common ownership of a research software project. In practice, a code review is nothing else than a conversation between the author of the code and somebody else providing feedback on coding practices, readability or other aspects of code quality. If this sounds straightforward, an effective code review routine can be tricky to establish. Here are five tips for you to get started with code reviews or get involved in more of them.

1. Keep it small

 Going through code, whether you are reading or explaining it to someone else, demands a lot of focus. In fact, several studies show that the efficacy of code review plummets when the code under review is too large and the discussion is too long. For this reason, it's best practice to limit code review meetings to about 45 minutes at the maximum. As a code author, do not plan to go through the entirety of your code. Rather, select a small portion of it: a short script, a few functions or a single class. Keep in mind that the more representative of the overall codebase this portion is, the more useful the feedback will be. It's also worth stressing that code review isn't something you do only once. For larger codebases, it's much more efficient to plan several, short code review meetings, rather than one very long one. 

2. Agree on objectives before the review

Code review is a difficult exercise. Time is of the essence, and you've got to narrow the discussion down to what matters. Feedback must be adapted to the author's level of experience and scientific context. Conversations can go off tangents. However, code review is much easier if the authors and reviewers agree beforehand on what they want to get out of it. For instance, authors may be interested in improving the readability of their code, with little regard for performance. Or reviewers may be particularly interested in learning about a specific use of a language. Agreeing on (a) objective(s) is key to an efficient and constructive discussion. It is also an opportunity for both reviewers and authors to introduce each other, state their level of experience, and voice their expectations. 

3. Adapt your communication 

Code review is often mistaken as a purely technical exercise. First and foremost, it is a communication exercise. As a reviewer, keep in mind that you are criticizing somebody else's work. Your role is not to assess their worth as a programmer, but instead to provide feedback on the code. Consider phrasing feedback from your own point of view and, as much as you can, offer alternatives. For instance, instead of 

 

“You named this function badly”

you could go for: 

“I would name this function differently, because…”

or 

“I couldn't guess what this function is doing from its name.” 

 

If you are the code author, on the other hand, keep in mind that reviewers are making an effort to get their heads around your code. In the heat of the moment, it is often easier to offer blunt feedback. Try not to take it personally and put your pride aside. It's always easier to see problems and improvements in somebody else's work. At the end of the day, your goal is to improve the code and learn from your peers. 

Whether you’re an author or a reviewer, it is crucial that you keep in mind your interlocutor's expectations and level of experience. An experienced research software engineer should provide/respond to feedback differently whether they are talking with a graduate student or an experienced colleague. 

4. Come prepared 

It's a good idea to make the code under review available to (the) reviewer(s) a few days before the review. This gives them the chance to browse through the code, form an independent opinion and write down some initial talking points. If you are the code author, be sure to refresh your memory of the code before you meet the reviewer(s). Be prepared to explain the code's design, main data structures and data flow. 

5. Do it often 

Don't wait until you feel comfortable showing (off) your code. Code review is like pushing a swing: do it at the right frequency and you'll get short, smooth, and impactful code review meetings. Do it once in a while and you'll have to push much harder. Don't mistake code review with academic paper peer review: code review should be informal and low-stakes. More importantly, it should be routine. Buddy up with a few colleagues in your lab and commit to reviewing each other's code two or more times a week. You act as a reviewer one day and have your code reviewed another day. And it doesn't matter if you haven't made progress or got stuck: the mere act of talking about it will move you forward. 


Want to discuss this post with us? Send us an email or contact us on Twitter @SoftwareSaved.  

Share this page