My humble opinion on the necessity of a check-in process Link to heading
Are you familiar with the situation of getting a code review that is being delayed by your peer reviewer’s nitpicking for filling his code perfection aspirations? Unable to commit due to build server failure? Personal preferences overruled over technical facts?
Let me see your unit tests
All the above are examples of the necessity of a well-defined procedure, guiding us in various situations we encounter daily. It defends our best interest, helps us understand how to handle them based on the collective experience of all SW engineers before us.
In the following lines, I won’t deal with the essential need for code reviews and how to perform them, a fact that being dealt in various articles (#1, #2, #3), even by the humble writer of these lines (link). Here, I focus on the crucial need for writing down the day to day team’s code review best practices.
Bureaucracy — again 🤦 or Why do we need it? Link to heading
Bureaucracy
The primary purpose of a code review is to make sure that the overall code’s health is improving over time. For achieving this goal, numerous trade-offs have to be balanced. Hence a well-defined process for both code review parties assists in bridging any gaps, settle down conflicts and allowing to move faster.
Which decreases the chances of something going horribly wrong during implementation. At the end of the day, making the code better without mental investment how to perform it.
So, What should it cover? Link to heading
It really depends on the team, its daily routines, the development environment, the chosen development methodology, and more preferences in which the team has decided to focus.
I highly recommend having a meeting with the entire team to consult what should make it in, since it is an essential part of the SW engineers’ work. It has a significant effect on everyone, reflected in the team’s motivation.
The guidelines should be brief, written in plain simple language, may include graphics (screenshots, etc…), summarizing the team’s (and the organization) best practices.
OK, say I’m convinced How do you suggest to maintain it? Link to heading
It doesn’t matter. just make sure it is written down, either on a document or on a dedicated web-page; there are plenty of ways to share information these days. With one important rule, it should be in a highly accessible location. Otherwise, it will reduce its effectiveness, collect dust and basically not relevant.
Shared location
Overall Link to heading
By doing so, you’ll increase team productivity, improve the codebase quality. And as a by-product of this process, inexperienced engineers will be mentored — leading to a highly effective team, better products, and happier customers.
IMHO, one of the best examples for such a code review guidelines, which covers the above points is the comprehensive document created by Google Developers, “How to do a code review”.