Engineering Review Comments

Review comments should improve the code and the developer's future judgment. They should be clear about severity, grounded in engineering reasoning, and directed at the code rather than the person.

Adapted from Google Engineering Practices Documentation, especially "How to write code review comments" and "Handling pushback in code reviews." Source: https://google.github.io/eng-practices/review/reviewer/comments.html. License: CC-BY 3.0.

Comment Shape

Use this structure for non-trivial comments:

SEVERITY: Observation about the code.

Why this matters: engineering reason, user impact, maintainability impact, or violated project rule.

Requested action: concrete fix, question, or decision the author needs to make.

Keep tiny comments tiny. Use the full shape when intent could be misunderstood.