As a software engineer, I do or receive code review nearly daily (except probably Saturday’s and Sunday’s ?). At the beginning of my career, I haven’t paid a lot of attention to the exact way how code reviews were provided. If they contain any clues to what can be improved – it was ok for me. After spending some time on this side of the software development process, I have made conclusions from my reactions about what, in my opinion, makes good reviews even better. And under these, I not only mean the emotional reaction to the feedback but more willingness level to make changes and make this PR be merged. You probably know what I am talking about here. A moment when you have finished reading code review, and you are still smiling, and it is clear for you what needs to be changed or where you should look in for better ideas on how to make this task be done.
So what can we all do better in case we are reviewers?
1. Be positive with your review.
Even though that, probably, main aim of review is to point out places where code can be improved, I believe in the same way it is important to emphasize parts, where one has done any additional work, that will improve future of the code base, or where one has done something in the smart way that does not affect readability in a bad way, or you have learned something new reviewing this part of code. If we will pay attention to these patterns and prize them, it will motivate others to do it more often. There are many ways how to express your emotions about someone’s code, starting from simple “Good idea” comment and comments with funny GitHub emojis, or coll gif, and up to whatever your fantasy can bring you to.
2. More ask and less make statements.
When I am reviewing code, I am trying to keep in mind that I will spend at most a few hours on this code review. Still, the person that has created this code, probably spend much more time, a couple of days, or if it is a PR that is trying to bring new idea/tools/feature to project, then one could spend weeks before this has been summarized in elegant PR, that I am currently reviewing. So, in this case, there can be many not straightforward reasons why this was done in this exact way. I think it is quite good instead of making the statement that this was done poorly/wrong/not efficient etc., ask in the comment why it was done this way (in general I think “why?” is one of the most powerful words in many cases). It can end up that there was the only way to implement this, and at most, some comments should be added or/and some names should be changed.
Even if you are up to make a statement in the comment, try to avoid using “you” directly. For example, it is possible to write “You are changing here state directly,” but the phrase “State here is changed directly,” in my opinion, has less blaming shade and provide the same information about what should be fixed.
3. Add illustration to explain expected or wrong behavior.
Even though that I think describing behavior in words is a handy way to communicate what you want to be done/changed, etc., I think it is as wells useful as an addition to include any needed illustration. I can’t think about more powerful and short way to explain what exactly (for example) part of the component UI you want to be changed, than add screenshot of the component with a red (or any other color you love) arrow pointing out to that part (LightShot has very simple way to do this). Working in Webflow I have learned one more powerful and simple in the same time way to visually communicate what is component UI behavior that we want to describe – make small gif 😉 This isn’t genius advice, as probably most everyone has done video with app/component behavior, but quite genius part is about gif format itself, as it can be loaded as an image, and will be autoplay in the comment directly without any additional action needed from the user, and will be visible in review (not just link to video anymore :)). LICECap is quite usable software to do these small and super helpful gifs. What I like in LICECap, that it is creating tiny files without losing quality, so they can be uploaded to GitHub comments.
4. Include links and examples, so a person could easier grasp what was meant.
Sometimes it is just Friday after tough week when one can feel just tired and not in 100% their smartest capability, or person whom code you are reviewing is dealing with something for the first/second time, or it just a super rare case, that is happening one time in the year in the code. No matter what is the real reason, but I think it will be cool if we will try to read our review comments and to think about them: “Is here crystal clear what should be done/changed?”. For example, one is using in JSX arrow function to bind some values why iterating an array. And reviewer can leave the comment “arrow functions shouldn’t be used in JSX”, but this quite awkward case when it is coming to fixing it. So, in my opinion, it will be much more useful to leave comment “Arrow functions shouldn’t be used in JSX. Please, check here https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-bind.md#lists-of-items how this can be fixed”. (let’s leave the discussion about do arrow function in JSX affect performance or not out of this post).
Reality is that all we are humans, and we even can know nearly everything, but do not remember at this particular moment or day.
5. Approve with fun. The world is already too serious.
For the first time, I have seen this in a review of my code. In 2016 (as far as I remember) GitHub have added this possibility to left comments with approving all PR (actually the whole system for having review happening all together was added then) and @adambretz have done the review of some my PR, and in the approving comment had added this gif:
When I first saw it, I burst out laughing, and my mood was 100% up. Not a bad result just for one picture 😉 I as well believe that a positive atmosphere is making us more opened to feedback, we have more significant willingness to learn something new, and we have more fun living our lives.
Even though I have made these conclusions for myself from the code reviewing process, I think they are applicable in the broader sense, as we are giving and receiving feedback in many other life cases, formal and informal ones. I like, what my manager taught me, that we should give each other feedback like we really and genuinely care about each other, then it will work and provide all the benefits for which all this idea with feedbacks was created in the first place.
If you have found a spelling error, please, notify us by selecting that text and pressing Ctrl+Enter.
