UX Notes for Code Review Process

UX is important and it can not be ignored. When your contribution is going to be used by peoples other than you, you must think of the user experience so that the user does not face any problem in using or extending the work you have done.

For example - if you are a developer contributing to a project, you need to follow the standards so that everyone in the team understands and the project does not go in maintenance hell. If you are a designer building user interfaces, you need to understand the user’s psychology so that the user don’t need to think while using your interface. So UX is always domain specific but at the core it has to be simple and minimal. When this goal is kept in mind you will be closer to understand your user.

In this post, I’ll be writing UX guidelines and thoughts around code review process and how to make this process more interesting and interactive.

In the code review process, the goal of every individual is to avoid any buggy code to be shipped in production. Also these sessions sometimes additionally help in mentoring new contributors in the team. Though this process involves multiple individual’s minds, it brings many challenges such as this approach is better than that and so on.

From either side (reviewer or submitter), if they are not on the same page, it might make the comment thread lengthier since to solve any problem there can be multiple approaches. And members might not be on the same page, when this situation comes the better approach would be to discuss offline, do research, mutually decide and record the notes in the MR.

Image Credit: imagemag.ru

To simplify this process from each side, I have written points section wise, so that you can relate to the persona you belong to at any given time. But before I write these points, I’d love to add the ten commandments of egoless programming which I think one must understand to avoid any miscommunication and help in building a quality review process. Where these points are not just limited to the code review process, but this is where most of the critical interactions are done. So here it goes-

The Ten Commandments of Egoless Programming

1. Understand and accept that you will make mistakes. The point is to find them early before they make it into production. Fortunately, except for the few of us developing rocket guidance software at JPL, mistakes are rarely fatal in our industry. We can, and should, learn, laugh, and move on.
2. You are not your code. Remember that the entire point of a review is to find problems, and problems will be found. Don’t take it personally when one is uncovered.
3. No matter how much “karate” you know, someone else will always know more. Such an individual can teach you some new moves if you ask. Seek and accept input from others, especially when you think it’s not needed.
4. Don’t rewrite code without consultation. There’s a fine line between “fixing code” and “rewriting code.” Know the difference, and pursue stylistic changes within the framework of a code review, not as a lone enforcer.
5. Treat people who know less than you with respect, deference, and patience. Non-technical people who deal with developers on a regular basis almost universally hold the opinion that we are prima donnas at best and crybabies at worst. Don’t reinforce this stereotype with anger and impatience.
6. The only constant in the world is change. Be open to it and accept it with a smile. Look at each change to your requirements, platform, or tool as a new challenge, rather than some serious inconvenience to be fought.
7. The only true authority stems from knowledge, not from position. Knowledge engenders authority, and authority engenders respect – so if you want respect in an egoless environment, cultivate knowledge.
8. Fight for what you believe, but gracefully accept defeat. Understand that sometimes your ideas will be overruled. Even if you are right, don’t take revenge or say “I told you so.” Never make your dearly departed idea a martyr or rallying cry.
9. Don’t be “the coder in the corner.” Don’t be the person in the dark office emerging only for soda. The coder in the corner is out of sight, out of touch, and out of control. This person has no voice in an open, collaborative environment. Get involved in conversations, and be a participant in your office community.
10. Critique code instead of people – be kind to the coder, not to the code. As much as possible, make all of your comments positive and oriented to improving the code. Relate comments to local standards, program specs, increased performance, etc.

Now let’s jump on the points for submitter and reviewers.

Are you requesting for your code to get reviewed?

• Make sure you have followed all the coding convention and it’s structured as standardized by the team members.
• Do not repeat the same mistake as pointed out by your previous code reviewers :)
• Write abstract points of change being made in a single diff.
• Test your changes every time you make any smaller change. If you do not test because it takes more time? Automate it!!
• Write comments, especially wherever you have made an assumption.
• Make sure you have at least reviewed your own changes before asking someone else to do.
• Get your code reviewed by more than a person. More eyes mean more errors, problems can be caught in the review process itself.
• Always seek for constructive criticism of your contributions.

Are you reviewing the code?

• Be nice, humble and if the code is not written as you expect, explain this to the submitter. Treat him/her as a human.
• Review carefully, just scanning the lines while reviewing is the reason why bugs are introduced to master in the first place.
• Give feedback if someone has just started writing code and help them in getting better at it.
• Don’t do code review because you have to just do it. Do it because you care to not ship buggy code to master.
• If you are not expert in the part of code sent for reviewing, ask an expert candidate to involve.
• Appreciate if some part of logic is out of the box, remember you are interacting with a human on another side. This will motivate him/her.

That is all for this post. If you have any thoughts on the same, feel free to add comments! Thank you for reading. Happy coding!