Chapter 2 · Practice 5 of 6
Check names, comments and documentation explain the code to the next reader
Why it matters
The rest of the review is about whether the next developer can understand and change this code.
| Area | What to check |
|---|---|
| Naming | Is each name long enough to say what the thing is or does, without being hard to read? |
| Comments | Do comments explain why the code exists or why it is done this way, rather than repeating what it does? |
| Style | Does it follow the team's style guide? Is a large reformatting kept in a separate change? |
| Documentation | If the change affects how people build, test, use or release the code, are the README and docs updated? Are removed features removed from the docs too? |
If the code is so complex that it needs a comment to explain what it does, the guide suggests making the code simpler instead. Comments are for intent and reasons, such as why a workaround exists or why an obvious approach does not work.
Example
// Restates the code: adds nothing
// increment retries by one
retries += 1;
// Explains why: worth keeping
// The provider returns 503 during its deploys, which last under a minute,
// so we retry with backoff instead of failing the payment immediately.
retries += 1;