Table of contents
Code Reviews have such a key role in the development process. In addition to saving valuable time and money, they also give a human-centric value to development teams. They are also a great tool for teaching and mentoring new recruits and an overall good practice big companies swear by.
But of course because of tight deadlines, sales expectations, and organizational pressures, some teams and companies are passing up opportunities to increase code quality.
Regardless of where your company falls on the spectrum of code reviews fandom, this piece will cover how you can (and should) use code reviews to help the development process and other aspects of the organization’s culture, and most importantly, give more value to your developers
Here are the 5 Golden Rules of Code Reviews:
There are five Golden Rules of Code Reviews. Some of them might sound familiar if you've been involved in training. And that's exactly right – code reviews are just one specific format of giving feedback in a particular domain.
Always remember - it’s a human being on the other end of the review
The first Golden Rule of Code Reviews is simple: Review other people’s code like you’d like your code to be reviewed.
Code reviews should:
- Be kind– even if there’s room for improvement, the message can be delivered with empathy
- Be clear– make it easy for the reviewer to understand what you are saying. Importantly, if you have constructive feedback to give, be direct about it. Avoid a “crap sandwich” that starts with positive feedback about the code, even if it’s genuine, before getting to your suggestion for improvement.
- Be specific – The more granular your feedback can be, the more helpful it is to the Author.
That can be hard to do when so many of us work remotely or hundreds or thousands of miles away from each other.
To make sure you are communicating correctly, read your code review to yourself out loud and ask yourself, is this something I would want to be said to me? If not, think about changing the tone or content.
Give clear suggestions or recommendations
Never tell someone that the code needs to be fixed without giving suggestions or recommendations on what to fix or how to fix it.
Not sure why? Imagine someone came to your home and said, “I don’t like your decor. Fix it.”
It is incredibly annoying.
It is never a good idea to write “Fix this” without giving more explanation. Why does it need to be fixed? What suggestions do you have to fix it? How might someone figure it out?
On behalf of the Code Review powers, we will personally come to your home to rap your knuckles if you ever leave a code review that only says “Fix this” or “Do better.”
Always assume good intent.
Code may not be written how you would write it. Let’s say that more clearly: code is rarely written the same way by two different people. After all, code is a craft, not a task on an assembly line.
Tap into a sense of curiosity and appreciation while reviewing – curiosity to understand what the reviewer had in mind and gratitude for what the Coder did or tried to do.
Clarify the action and the level of importance.
If you are making an optional suggestion, for example, a “nit” that isn't necessary before the code is approved for production, say so clearly.
If you wonder why the person made a particular choice, but it doesn’t affect whether the code should make it to production, say so clearly.
If you are confident that the code needs to be fixed before it is ready for production, say so clearly.
Pro tip: When writing, we frequently think that our intent is clear. After all, we know what we are trying to say. But remember that our writing may not always be as clear to the reader as it is to us, and make sure that your most fundamental guidance is plain and straightforward.
Don't forget that code feedback – and all feedback – includes praise.
It goes without saying that the key benefit of doing code reviews is to make the code better and fix issues.
But that's only half of it. On the flip side, code reviews present an excellent opportunity to thank you and appreciate your colleagues' work.
If someone has written particularly elegant or maintainable code or has made a great decision about using a library, let them know!
At Sema, we say it is always the right time to give positive, specific feedback. But, of course, we walk the talk when it comes to code reviews too.
Find out more about the ins and outs of code reviews and their impact on company culture in our whitepaper: www.semasoftware.com/blog/code-reviews-101-the-basics
