A code review is the examination of source code with the goal to improve the code, the knowldedge of the author and the reviewer. A code review takes time but saves time and headaches in the future.
Do not confuse the code review with a design review (also called architecture review). In a design review you can discuss the architecture (the big structure) of your software. It is possible to formalise this activity by writing a design document which explains the planned structure of your code and submitting this to a reviewer. Ideally, this should happen before the implementation of the software. The design document can contain text and diagrams that explain the whole architecture and the structure of the data flow.
- Spot errors that might change the results
- Improve the code (readability, reusability, performance, etc.)
- Learn from each other
Big software companies like Google often require a formal code review of every change to the codebase of a product. Special tools integrated into the version control system allow employees to request code reviews only for the changes since the last review.
Small software development teams sometimes favor the more informal over the shoulder (OTS) code review. During an OTS review, the programmer explains his code to the reviewer who will ask questions, ask for changes or clarifications.
In our lab we work on very different projects. Therefore it might be useful to start with an OTS-review where the author explains the structure of the program to the reviewer. Later, a formal code review is helpful for a look at the details.
If you (the author of code) want your code to be reviewed, please try to make life easy for the reviewer by making it easy to read your code.
-
Prepare your repository:
- you may want to review the code by yourself first. Ask yourself the question: will someone else be able to understand what you want to do in every line of code?
- programming languages can be written in a specific style. Use a good style guide for your language (Python, R, (google for "programming language" style guide)) and adhere to it.
- make sure your code does not depend on very specific requirements that are only met on your PC.
- write a readme-file. Read this guide on what should be included in a readme-file.
- use Git. This allows us to do incremental code reviews. It also shows you what the reviewer changed.
- use Git and Github for bigger projects to allow incremental code reviews with the tools of Github.
-
Find someone who is willing to do a code review for you
- it is easier to do several short reviews. Ask early!
- Make the reviewers life as easy as possible by writing simple code, good comments and a good readme/documentation.
- the reviewer should know the programming language. He/she should also know and understand the problem that this software tries to solve.
-
The duties of the reviewer:
- Be kind but don't hold back.
- really: be kind!
- read the code (line by line) and check whether the code
- does what it is supposed to do
- adheres to the style guide
- is simple, understandable
- could be easily optimized
- pay attention to special requests of the author
- you can edit the code in place, add a comment next to the specific code line and write broader thoughts in one statement.
- if your comment is not essential for the functionality but more educational, preface the comment with "nit:".
-
Receive the results
- the reviewer is not always right, but consider his opinion.
Code Review For and By Scientists: Abstract:
We describe two pilot studies of code review by andfor scientists. Our principal findings are that scien-tists are enthusiastic, but need to be shown code re-view in action, and that just-in-time review of smallcode changes is more likely to succeed than large-scaleend-of-work reviews."
Code reviews: the lab meeting for code Guidelines derived from scientific group code reviews. E.g.:
The most difficult part of writing code is always to make it understandable to other people, including yourself a few months down the track. There’s certainly no shame in finding out that your code wasn’t as easy to understand or use as you’d hoped, so don’t take it personally when it happens (which it always does, at least in my experience), but treat it as an opportunity to improve.
Here’s some general guidelines for making your code review go smoothly:
- Make sure the motivation for your code is clear. Someone who isn’t intimately involved with your project should understand from the module documentation and the comments what you are trying to do, what approach you’re taking, and why they should expect it to work.
- Take some time to prepare a presentation about your code that will answer the above questions even for someone who hasn’t read the code. You’re more likely to get useful feedback, rather than nitpicking about syntax, if the audience can see the big picture.
- Get the code sent out at least a few days beforehand along with some background about what to look at (if large), whether suggestions should be about architecture/implementation/algorithm/requirements, etc. Make sure everyone has enough time to read the code beforehand, and don’t send a series of updated versions immediately before code review.
- Don’t try to present too much. 200 lines is an absolute maximum – 50 is usually more reasonable.
- ...
Code review guidelines by codeproject is a document like this one and explains the why and how with practical tips for reviewers and authors.
11 best practices for code review
- Review fewer than 200–400 lines of code at a time
- Take enough time for a proper, slow review, but not more than 60–90 minutes
- Be sure that authors annotate source code before the review begins
...
Code Review Guidelines for Humans - How to do code reviews without destroying relationships.
List of links with content about code reviews - https://github.com/joho/awesome-code-review
Google Engineering Practices Documentation - https://google.github.io/eng-practices/
https://en.wikipedia.org/wiki/Software_architecture
https://en.wikipedia.org/wiki/Code_review
The Clean Code Cheat Sheet defines rules for good coding practices.