Warning: Constant ABSPATH already defined in /home/public/blog/wp-config.php on line 23

Warning: Cannot modify header information - headers already sent by (output started at /home/public/blog/wp-config.php:23) in /home/public/blog/wp-includes/feed-atom.php on line 8
Page not found – Dysfunctional Programming /* You are not expected to understand this */ 2017-02-09T19:27:11Z https://www.joshmatthews.net/blog/feed/atom/ WordPress Josh Matthews http://joshmatthews.net <![CDATA[Code review: gatekeepers vs. coaches]]> https://www.joshmatthews.net/blog/?p=224 2017-02-09T19:27:11Z 2017-02-07T06:47:59Z I wrote a list of code review guidelines for the Servo project last year. They encapsulate the feedback that we expect our project contributors to provide when reviewing code changes, but I want to explore the motivation behind them.

You’ll notice that almost every step is in the form “look for X”, followed by “suggest how to improve X”. This is not an accident; I find code review most effective when it is both constructive and collaborative. When a reviewer leaves a comment indicating that the current change is not optimal, this suggests that they have an optimal form in mind. If the reviewer does not (or cannot) describe their ideal outcome, they are setting the author of the changes up for failure.

Sometimes when I review code, I have a feeling that if it were written differently then the result would be better in some respect (maintainability, readability, performance, safety, etc.). When I can articulate this feeling as a concrete change I would like to see, one of several outcomes occurs:

  • the author makes the change and agrees with my reasoning
  • the author makes the change but disagrees with my reasoning, sparking a discussion about a specific result
  • the author explains why my change is inappropriate based on prior experience with the code in question

All of these outcomes are beneficial – either the code is improved, or at least one party ends up learning something new about the code that’s being changed. This is one of the benefits of a collaborative code review process!

Other times when I review code and I feel that a change could be improved in some way, I find that I am having difficulty describing the specific improvement I have in mind. When this happens, I can:

  • locally modify the changes under review to see if my idea is feasible
  • create a minimal, representative sample of the change and demonstrate the transformation I have in mind
  • decide that my idea is not worth the additional effort that would be required to achieve it

Once again, all of these outcomes are beneficial – either I now have concrete feedback that can be discussed, or I have decided that my idea should not be pursued (whether it’s based on incorrect assumptions or not a good use of time).

These are the guidelines that I try to follow as a code reviewer. My role is not merely a gatekeeper, evaluating whether code changes should be merged or not. Instead I am a coach, helping shape the changes into a form that will leave all parties satisfied.

]]> 0