Conventional Comments
Follow conventionalcomments.org spec: <label> [decorations]: <subject>. Local conventions below.
Workflow
- Read the full diff before writing any comments.
- Address blocking comments first — they gate approval.
- Add non-blocking feedback after.
Local conventions
- Forbidden labels:
praise,nitpick,quibble— actionable feedback only. Useissue,suggestion,todo,question,note,typo. - Blocking indicator: append
!directly before:(e.g.,issue(security)!:). Local extension to the spec — use this in place of the(blocking)/(non-blocking)decoration. Absence of!means non-blocking. - Domain decorations:
(a11y),(performance),(security),(ux). - Silence is a valid review output — no comment if the code is self-explanatory and correct.
Label boundaries
issuebreaks correctness or contracts.todois a gap that should be closed but is not immediately harmful.suggestionoffers a better approach (include the alternative).todopoints out something missing.questionexpects a response.notedoes not.
Anti-patterns
- Restating the diff. State the consequence, not the change.
- Suggestion without alternative. Always include the concrete change.
- Rhetorical question. If you know the answer, use
suggestionorissue.
Example (combining local conventions)
issue(security)!: User input embedded directly in SQL.
Use prepared statements to prevent SQL injection.