10 May 2022 by Phillip JohnstonAuthors can greatly improve the code review process through preparation. Some of this will come naturally, since the pressure of having code reviewed by another person will push people to develop code to a higher standard (i.e., to avoid the pain of receiving a flood of feedback). The use of a disciplined preparation process will also help the author identify defects before the reviewer sees the changes, and it will also ensure that the reviewer’s job can be executed more efficiently, increasing the throughput of reviews and enabling reviewers to focus purely on finding defects. …
Continue reading “Prepare Your Code for Review”
10 May 2022 by Phillip JohnstonA common developer complaint regarding code reviews is “I spend a lot more time figuring out what the code is supposed to be doing instead of finding actual defects.” This statement is a bit ironic, because it is one of the primary things we focus on as reviewers – especially as consultants who are hopping in and out of code bases that we are unfamiliar with. If a reviewer cannot figure out what a piece of code is supposed to be doing during a review, that is a defect! Anyone on the team should be …
Continue reading “Effective Code Review Requires Annotation and Documentation”
10 May 2022 by Phillip JohnstonIt is popular at the moment to rail against code reviews as waste, especially when teams adopt beneficial practices such as pair programming, static analysis, testing and automated standards enforcement. After all, if we have invested time to put these practices and processes in place, why do you need to “waste time” reviewing code when developers could instead be writing more of it? Certainly, there are other processes and practices you will adopt that will aid you in finding defects and improving the quality of your code even before it hits the review stage. But …
Continue reading “Automated Quality Enforcement Does Not Eliminate The Need for Peer Code Review”
10 May 2022 by Phillip JohnstonWhile primary purpose of a code review is to find defects in the code, they are also used to ensure that code meets the team’s standards. However, many code reviews are painful precisely because team’s don’t have documented standards, causing reviews to devolve into debates about style or into a war of personal preferences. One way to significantly improve your code reviews is to have your team sit down and agree upon standards that code will be judged against. Nobody likes to be surprised, and that is especially true when receiving feedback from reviewers. It …
Continue reading “Use Standards to Ground Code Reviews”
9 May 2022 by Phillip JohnstonA common difficulty with code reviews is that they often degrade into debates about style. There is a simple solution to this: do not allow debates on style in a code review. Likewise, do not allow debates on whether or not the style guide is correct. Instead, focus the team on identifying defects and deviations from agreed upon coding standards. The best approach to eliminating debates about style is to automate the formatting process. There are a number of code formatting tools that can be used to specify and enforce a specific coding standard. Have …
Continue reading “Code Reviews are not About Style”
9 May 2022 by Phillip JohnstonReviews in software engineering are a touchy subject, with many programmers actively fighting against participating in reviews. These difficulties arise from many factors: Many programmers have no professional training in software at all, which leads to low quality reviews Reviews are focused on things like style and formatting rather than on finding fundamental issues with the code Programmers are not trained to give feedback in a constructive way, e.g. reviewers make personal attacks on intelligence and ability.) Professional discipline is rarely a topic that is emphasized in schools that teach CS and software engineering Difficult …
Continue reading “Common Difficulties with Code and Design Reviews”
9 May 2022 by Phillip JohnstonWhen reviewing code, search for TODO or FIXME style comments in the changes. These comments indicate unfinished work, and they should not be merged in. Some developers may indicate that the comments are not related to their current changes, but instead: Were previously deferred work, not something they added with the change set Aren’t required in the current changes, but serve as reminders or placeholders for upcoming work If the upcoming or deferred work is important enough, it should be tracked as an issue or task within the team’s system of choice so that it …
Continue reading “Look for TODOs and FIXMEs Comments During Reviews”
9 May 2022 by Phillip JohnstonCode reviews be focused on identifying defects with the code. However, the reviewer should not provide fixes for the problems – the author is a smart person who can come up with solutions on their own, and they can do so once all feedback is received. If the author would like input on how to address the defect, they are free to ask. References Code Review Guidelines A Guide to Code Inspections by Jack Ganssle During the meeting we don’t invent fixes for problems. The author is a smart person we respect who will come …
Continue reading “Find Problems During the Review – But Don’t Fix Them”
9 May 2022 by Phillip JohnstonSimply identifying a problem during a code review is not sufficient: it also needs to be addressed! You might this point is an exaggeration, but we have seen plenty of code merged in the name of expediency even with glaring review feedback… and of course, the team was never able to “go back and fix it when things slowed down.” The typical way to verify that defects are actually fixed is to have the subsequent changes reviewed once more. Depending on the defect, it may be appropriate to request additional test cases to verify the …
Continue reading “Verify that Defects are Actually Fixed”
9 May 2022 by Phillip JohnstonThis is the most important factor to understand when reviewing code: code reviews are about the code, not about the author of the code. Keeping this firmly fixed in your mind can help you avoid many of the pitfalls that arise around code reviews. The primary objective of a code review is to find defects within the code. The more defects you find, the better. The problem is that the human who wrote the code probably feels worse as the number of defects found increases – and this is especially true when metrics are collected, …
Continue reading “Code Reviews Are About the Code, Not the Author”
