Conventional Comments: How Better Labels Make You a Better Software Engineer

As a Software Engineer, 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

Feels vague. Sounds harsh. No direction.

Unlabeled comments often:

Sound more aggressive than intended

Leave the reader guessing about intent

Create unnecessary back-and-forth

The Fix: Add a Label

✅ Label your comments

Labels immediately clarify intent, priority, and tone—before the reader even finishes the sentence.

Labels set expectations early and reduce misinterpretation.

Examples of Conventional Comments I Commonly Use

Below are practical examples showing a basic version and a better version, with explanations for why the improved version works.

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, non-accusatory tone

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

3. TODO

Basic

@paul to add test coverage.

Better

todo: Add unit tests for the error-handling path in `useAuth`.

This should cover the unauthorized and timeout cases.

Why it’s better

Avoids hard 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 useful future context

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 clear 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.

Perfect for PR reviews, RFCs, and quick feedback.

Key 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?

Clear comments scale better than clever ones.