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 the reviewer thinks the 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 reasoning and
- help authors learn and improve.
Here are two examples:
Example 1 (Code)
- This field access could cause a null pointer exception.
- The receiver in the field access expression is the object returned from the method call on line 34 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.
- 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.
- 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 Dev.to.]