A Code Review can sometimes be a painful process. Reviewing code takes time and attention and human beings do not have an unlimited supply of either.
But, it does not have to be that way. There are things we can do to make a code review less painful.
There are two parties in a code review: The Author and the Reviewer. A Code Review begins when an Author sends to a Reviewer a list of changes they made to an application. The Reviewer then looks at the code and either approves it or makes suggestions and sends it back to the Author. The process repeats until the Reviewer approves the changes.
The Author's changes are known as a "Change Set"; the description of those changes is a "Change List"; many Application Lifecycle Management tools (e.g., GitHub and Azure DevOps) support a "Pull Request", which combines the two with the source code and is a formal entry point for the Reviewer to begin reviewing the code changes. I often use these three terms interchangeably because they are so closely related.
In my last article, I describe ways that the Reviewer can improve the Code Review process.
In this article, I will describe ways that the Code Author can improve the Code Review process.
Test Your Code
This should go without saying, but you should always verify that the code works before submitting it for review.
Spend time validating that your code works. Manually run your code. Write automated tests and run them as you make changes to your code. Vary the inputs and consider edge cases and unexpected user actions as you do. A small change can break things unexpectedly and automated tests are great insurance against this.
Become a Reviewer
Code Reviews take time and effort, and you should respect the time and effort that the Reviewer commits to the process. A final scan of your code often reveals obvious problems, such as spelling errors and redundant or unnecessary code. It can even reveal more fundamental problems, such as a bug you missed on the first pass. Taking a few minutes to review your code reduces the time and effort required by the Reviewer. As a bonus, your code will look better to the Reviewer, making them more efficient and encouraging a better relationship.
A Pull Request consists of a set of changes to the code. It should always contain a description of those changes. If you write a clear description of those changes, the Reviewer will know what to look for and their feedback will be more useful.
When responding to feedback, always communicate what you changed in response to that feedback. This will give the Reviewer an idea of what to look for and make it easier for them to read and evaluate your changes.
If anything is unclear in the feedback, solicit more information - either through comments in the PR, via email, or with a verbal conversation. Written communication is sometimes flawed and requires clarification.
Use the computer
As mentioned earlier, you should test your code before submitting it to a reviewer. Much of this can be done automatically using the computer: Compile the code; run all automated unit tests; and use a linter to check the code style against a set of pre-established rules.
Answer questions with code
The clearer you make your code, the easier it will be to understand. Code comments can be useful, but you must take care to always keep them up to date with the code. The best way to clarify your code is to make it self-documenting. Well-written, self-documenting code will almost always communicate its intent better than code comments.
Spend some time refactoring your code to make it more readable. Here are some examples:
If you have lines of code that perform a property tax calculation, consider putting this into a method with a name like "CalculatePropertyTax". Calling this method is probably much clearer than trying to understand what the calculations do.
If you have a number or code with a specific meaning (for example, a tax rate or department id), assign that value to a constant, a variable, or an enum. It is much easier to read and understand this:
var taxDue = revenue * TAX_RATE
var taxDue = revenue * 0.23
Your goal should be to make the code as readable as possible. Consider questions the Reviewer might have and strive to make the code answer those questions.
Keep it Simple
I have seen too many Pull Requests that make a plethora of changes. It is best to create a Pull Request that only makes one change to the system (although you may choose to implement that change using multiple functions). If you are adding a new feature and fixing a bug, split these into two PRs. If you are changing two distinct parts of the system, split these into two PRs. Large PRs are confusing and overwhelming. The time and effort to review two PRs is almost always less than the time to review one large PR.
Breaking up large changesets can narrow the scope of your change, making each one easier to understand and review.
Sometimes, we create Pull Requests for non-functional changes, such as changing the formatting of our code. These often affect every line in a file. These should always be submitted as their own changeset. If we combine these changes with functional changes, it makes it nearly impossible to determine which lines had a functional change.
Code reviews can be a source of conflict. Code Authors often feel an ownership of the code they write to the point that they perceive any criticism of their code as a criticism of themselves. Avoid this outlook. Separate yourself from your code and do not take constructive feedback personally. It will be better for your mental health, and it will allow you to look more objectively at how you can improve your code. Respond graciously to the Reviewer's feedback. You both have the same goal: to improve the quality of the codebase. Keeping your cool can be especially difficult when you know the Reviewer is mistaken. Reviewers are human and they are allowed to be wrong sometimes and you should be patient when this happens. Consider that a lack of clarity in your code may be a source of a Reviewer's mistake and strive to address this.
Recognize there are multiple right ways to do almost everything in software development. If you are both correct, it will save time and effort to skip the debate and agree with the Reviewer.
This is similar to advice to the Code Reviewer. Delaying the time between receiving feedback and responding/working on the feedback slows down the entire process. The sooner you work on changes, the fresher will be the original code in your mind. The sooner you re-submit your changes, the more fresh will be the feedback in the mind of the Reviewer. This can be a challenge if you have begun some other work; but recognize that there are significant benefits to responding quickly to code review feedback.
Proactive thinking by a Code Author during a code review can make the whole process faster, more efficient, and more pleasant. Give a few thoughts on how you can make it better.