How to be a Good Reviewer?

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 (What)
2. Provide reasons why an issue is an issue (Why)
3. Suggest how to fix the identified issues (How)

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

1. assess the validity of your judgement and
2. help authors learn and improve.

Here are two examples:

Example 1 (Code)

1. This field access could lead to a null pointer exception.
2. The receiver in the field access expression is the object returned from this method call 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. The user may not know 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.