Independent of the artifact being reviewed (e.g., design doc, code, test, packaging, presentation, book), a good reviewer should do the following:
- Identify issues in the artifact (What)
- Provide reasons why an issue is an issue (Why)
- 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
- assess the validity of your judgement and
- help authors learn and improve.
Here are two examples:
Example 1 (Code)
- This field access could lead to a null pointer exception.
- The receiver in the field access expression is the object returned from this method call which can return null.
- Ensure the receiver object is non-null before accessing the field.
Example 2 (Documentation)
- The instruction is asking the user to set up an emulator.
- The user may not know how to set up an emulator.
- Provide instructions to set up an emulator or explicitly mention the user should be familiar with setting up an emulator.