Conventional Comments : How Better labels makes a Better Software Engineer
Writing Better Code Review Comments
As Software Engineers, we constantly balance technical communication and non-technical communication.
Writing good code is important — but writing clear, respectful, and actionable comments is just as critical.
Poorly written comments slow teams down, create misunderstandings, and introduce unnecessary friction during reviews.
The Problem: Vague Comments
❌ Unclear Feedback
> “Why are we calling this API twice?”
Short comments like this often:
- Sound more aggressive than intended
- Leave the reader guessing about intent
* Create unnecessary back-and-forth
* Lack context or actionable direction
Even when the intention is good, the delivery can create friction.
The Fix: Add Labels
✅ Label Your Comments
Labels immediately clarify:
Intent*
Priority*
Tone*
Before the reader even finishes the sentence.
They help reviewers understand whether something is:
* a question
* a suggestion
* a blocking issue
* a future task
* or just additional context
This reduces misinterpretation and keeps reviews productive.
Conventional Comment Patterns
1. Question
Basic
Why are we calling this API twice?
Better
question: Is there a reason we’re calling this API twice in the same request cycle? I’m wondering if this is intentional for caching, or if we can reuse the first response.
Why It’s Better
* Neutral and non-accusatory
* Shows curiosity instead of blame
* Suggests a possible direction without assuming a bug
2. Suggestion
Basic
Can we change this to match the wording on the marketing page?
Better
suggestion: Can we align this copy with the wording on the marketing page? That way, users see consistent terminology across the product and website.
Why It’s Better
Explains why* the suggestion matters
* Connects the change to user experience
* Adds context instead of only requesting change
3. TODO
Basic
@paul to add test coverage.
Better
todo (test): Add unit tests for the error-handling path in `useAuth`. This should cover the unauthorized and timeout cases.
Why It’s Better
* Avoids dependency on a specific person
* Clearly scoped and actionable
* Easy for anyone on the team to pick up
4. Note
Basic
We need to update our library version on the next sprint.
Better
note: This relies on `react-query@3`, which we plan to upgrade next sprint. No action needed here — just something to keep in mind.
Why It’s Better
* Explicitly non-blocking
* Provides future context
* Prevents confusion during later refactors
5. Issue
Basic
A vulnerable library needs to be updated before we deploy.
Better
issue (blocking): `lodash@4.17.20` has a known security vulnerability. We should upgrade to `4.17.21` before deploying to production.
Why It’s Better
* Clearly marked as blocking
* Specific and actionable
* Includes a direct resolution path
Ultra-Compact Cheat Sheet
question: Is this behavior intentional? suggestion: Could we simplify this to reduce duplication? todo: Add tests for edge cases. note: This will change once we migrate to v2. issue (blocking): This breaks on null input.
Useful for:
* Pull Request reviews
* RFC discussions
* Async collaboration
* Team feedback loops
Rule of Thumb
Good comments answer at least one of these questions:
* Why does this matter?
* What should happen next?
* Is this blocking or informational?
Final Thought
Clear comments scale better than clever ones.
A well-written review comment improves:
* team communication
* onboarding
* collaboration speed
* review quality
* long-term maintainability
Good engineering is not only about writing code.
It’s also about helping other people understand it.