Independent of the artifact being reviewed (e.g., design doc, code, test, packaging, presentation, book), a good reviewer should do the following:

  1. Identify issues in the artifact
  2. Provide reasons why the reviewer thinks the issue is an issue
  3. Suggest how to fix the identified issues

It is not sufficient to merely do 1 and 3. It is necessary to do 2 to

  • assess the validity of your reasoning and
  • help authors learn and improve.

Here are two examples:

Example 1 (Code)

  1. This field access could cause a null pointer exception.
  2. The receiver in the field access expression is the object returned from the method call on line 34 which can return null.
  3. Ensure the receiver object is non-null before accessing the field.

Example 2 (Documentation)

  1. The instruction is asking the user to set up an emulator.
  2. So far, the document does not state the user should know how to set up an emulator and here we assume the user knows how to set up an emulator.
  3. Provide instructions to set up an emulator or explicitly mention the user should be familiar with setting up an emulator.

[Original post is available at]

Programming, experimenting, writing | Past: SWE, Researcher, Professor | Present: SWE

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store