Summary: Many companies practice ‘code review’ to reduce technical debt. However, with more thought and care, ‘code review’ can influence company culture to nurture humility, open & positive communication, alignment towards greater good, and respect. This article proposes 3 simple steps to un-tap this latent potential of ‘code review’, which includes introducing 2 conceptual guidelines: ‘situational criticism’ and ‘intent-based criticism’.
Code Review Origins
Many years ago, the term code review would conjure up the feeling of tardiness in product development. Like ‘light’, which cannot be fully appreciated without ‘darkness’, technical debt, which was expounded in many blog posts, became the ‘darkness’ from which code review shone. Technical debt arises from each new piece of code that reduces the codebase’s overall maintainability and extensibility. This can result from the coder:
- Not being aware of a certain coding best-practice
- Not being aware of all the dependencies between different parts of the code
- Not fully understanding the original intent of a piece a code thus inadvertently clobbering any planned extensibility
- Overlooking better ways to build a feature due to tunnel vision resulting from one’s limited coding experience
- Constantly prioritizing feature deadlines over carefully crafted code, and not making up with code re-factoring thereafter
- Over-engineering, or pre-maturely optimizing code instead of releasing code often & early, leading to code bloat
Code review brings a pair of fresh eyes, that alleviates (not eradicate) the first 4 problems, and acts as a balance-and-check mechanism for the last 2.
Tangentially, code review also disseminates knowledge about the codebase across the team.
The Latent Potential of Code Review
Code review can exert far-reaching effects beyond reducing technical debt, and balancing development release cycles; when done with care, it builds great team culture. It nurtures:
- Humility: The team learns to accept that no one cannot be right all the time, and to err is human, thus they become open to positive criticisms
- Open & positive communication: The team embraces positive criticisms with open arms, as opportunities to learn, which in turn, encourages others to constantly proffer feedback
- Alignment towards greater good: The team understands the code review intent to improve the codebase, and the people working with it, thus always communicating with those at heart. Alignment on intent encourages everyone to tolerate conflicts, and ambiguity in favor of preserving the intent
- Respect: The team learns to respect guidelines, which has everyone’s interest built in, and where the guidelines fall short, everyone work towards respecting the greater good
Unfortunately code review and the culture it nurtures does not happen overnight, they demand that we work for it. Fortunately, with a set of coding, and behavioral guidelines, we can unleash its full potential.
Unleashing the Cultural Potential of Code Review
Code review, if advocated without supporting mechanisms, usually ends up in one of these extremes:
- Someone abusing code review as an opportunity to elevate her/his own status and suppressing others, which turns code review into nightmare
- Everybody playing it safe to preserve a harmonious environment by not being critical of each other, which defeats the purpose of code review
To overcome these, code review needs a formal declaration of intent (purpose), and a set of guidelines to support the intent.
Code Review: Intent
The code review intent focuses on the good of everyone in order to encourage them to get behind it, and utilize it as a tenet to defend against actions that undermines it. Code review should:
- Build maintainable and extensible code that is a joy to work with
- Improve everyone’s coding ability, and understanding of the codebase
Code Review: Guidelines
There are 2 types of guidelines (coding and behavioral) required to get everyone on the same page quickly on what preserves the intent of code review, and what constitutes violation. They also become a reference point from which to reconcile differences.
Coding guidelines
These are well-known coding practices accepted by the community, and they focus on code composition and code style. The former enforces coding principles, e.g., data integrity, which mandates using foreign keys in database tables, etc., while the latter encourages uniformity, which aids readability and comprehension, e.g., code preferences, which documents nitty-gritty like preferring while over for loops. There are many articles on both so I will leave you with a piece of advice:
“Don’t spend weeks pondering which best practices to use; start with any RIGHT NOW, and tweak as the team goes along”
Behavioral guidelines
It is easy to bandy about the phrase ‘positive criticism’ but it is too wide open to interpretation, and is overly reliant on the tact and prudence of the giver, which coders may not be naturally blessed with, especially junior ones.
To foolproof ‘positive criticism’, we demand that it should be both a situational criticism and intent-based criticism.
Situational Criticism
- A piece of criticism should be based on a particular piece of code, under a particular circumstance, at a particular instance of time
This disarms the criticism from insinuating anything persistent about the receiver, thus conveying a sense of exoneration, making it both easy to give & receive it.
Moreover, it transfers the onus of ensuring that the criticism is indeed situational to the receiver; the recurrence of the same situational criticism is tantamount to a reprimand for being a repeat offender.
Intent-based Criticism
- Any piece of criticism must uphold the formal intent of code review
Since the intent of code review is to improve everyone involved and the codebase, intent-based criticism has a positive vibe, and should be really useful, making it both easy to give and receive.
Concrete Examples of Code Review (Update 2018–06–02)
Here are a few ‘good’ code review examples that combine both situational, and intent-based code review, and a few ‘not good’ examples.
Good
Example 1:
Would it be easier to understand in the future, if we use a switch statement here?
- ‘easier to understand’: Articulate intent of making code easy to understand
- ‘use a switch statement here’: Make code review situational
Example 2:
In this part of the code, would using a factory pattern make it possible to handle new use cases in the future?
- ‘make it possible to handle new use cases’: Articulate intent of making code easy to work with
- ‘in this part of the code’: Make code review situational
Not good
Example 1:
It is good practice to use switch statement instead of multiple ifs.
- Lacking explanation of intent
Example 2:
You should use a factory pattern to ensure code can handle new uses cases.
- Implies that the coder does not understand factory pattern, thus code review does not seem to be situational
Note the good code review examples also are often suggestive, inviting discussion, or formatted into question form.
Data-driven Culture
If you are big on using data to power your company, and are a believer in continuous real-time feedback (instead of the hand-waving, “we have an open-door policy where you can come in and tell us about your problem anytime”), get started with a single-click on re:Culture to keep a pulse on how well the team is adopting code review.
Wrapping Up
We hope that you are convinced and excited about the potential role code review can play in building a great company culture. With 3 simple steps of formalizing the intent of code review, implementing coding guidelines with community best-practices, and implementing behavioral guidelines with situational and intent-based criticism, you have all the tools to transform your company culture.
Hacker Noon is how hackers start their afternoons. We’re a part of the @AMIfamily. We are now accepting submissions and happy to discuss advertising &sponsorship opportunities.
To learn more, read our about page, like/message us on Facebook, or simply, tweet/DM @HackerNoon.
If you enjoyed this story, we recommend reading our latest tech stories and trending tech stories. Until next time, don’t take the realities of the world for granted!