How to write better (code) review

As a software engineer, I do or receive code review¬†nearly on daily basis (except probably Saturday’s and Sunday’s ūüėā). On 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 own reactions about what, in my opinion, makes good review even better. And under these, I not only mean 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 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 actually 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 at most a few hours on these code review, but 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 totally 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 really the only way to implement this, and at most come comment 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, have less blaming shade and provide exactly 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 very useful 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 – just make small gif ūüėČ This isn’t genius advice, as probably most everyone has done video with app/component behaviour, 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 really small 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 very hard 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 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 own 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¬†¬†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 just 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 own 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:

uprove PR gif

When I first saw it, I actually burst out laughing, and my mood was totally 100% up. Not a bad result just for one picture ūüėČ I as well believe that positive mood is making us more opened to feedback, we have bigger willingness to learn something new, and we definitely 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 a more wider sense, as we are giving and receiving feedback in many other life cases, formal and informal one. I really like, what my manager taught me, that we should give each other feedback like we really and deeply care about each other, then it will work and provide all the benefits for which all this idea with feedbacks were created in the first place.

Olena Sovyn
Senior Software Engineer (London, UK). I ‚̧ React, Redux, lodash, React Storybook, and functional programming overall. Always open for learning something new

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Spelling error report

The following text will be sent to our editors: