Conventional Comments
Write code review comments in Conventional Comments format (https://conventionalcomments.org).
Format
<label>[!] [(decorations)]: <subject>
[discussion]
| Part |
Required |
Description |
label |
Yes |
Comment type (see Labels below) |
! |
No |
Blocking indicator—must resolve before approval |
(decoration) |
No |
Comma-separated context tags (e.g., (security)) |
subject |
Yes |
Main message (1 line) |
discussion |
No |
Additional reasoning or suggested fix (1-3 lines) |
Labels
| Label |
Description |
issue |
Identifies a problem that needs to be addressed. |
suggestion |
Proposes an improvement with an explicit change. |
todo |
Small, necessary change. Less severe than an issue. |
question |
Seeks clarification or investigation. |
note |
Information for the reader. Does not require action. |
typo |
Points out a typographical error. |
Do NOT use: praise, nitpick, quibble — focus on actionable feedback only.
Decorations
| Decoration |
Use when |
(security) |
Comment relates to security vulnerabilities. |
(performance) |
Comment relates to performance impact. |
(a11y) |
Comment relates to accessibility. |
(ux) |
Comment relates to user experience. |
Examples
Basic suggestion
suggestion: Consider using optional chaining here.
`user && user.profile && user.profile.name` can be simplified to `user?.profile?.name`.
Blocking issue
issue!: This function silently swallows exceptions.
Either log the error or propagate it to the caller.
With security decoration
suggestion! (security): User input should not be directly embedded in SQL.
Use prepared statements to prevent SQL injection.
With performance decoration
issue (performance): This query runs inside a loop causing N+1 problem.
Batch the IDs and fetch all records in a single query.
Simple todo
todo: Add null check before accessing `user.email`.
Question
question: Is this timeout value intentional?
300ms seems short for API calls that may span regions.
Note (informational)
note: This pattern is also used in `auth-service.ts:45`.
majiayu000