conventional: comments
Communicating thoughtfully in written reviews
Soft skills can be hard — especially in writing. Each word choice can affect how your message lands.
Conventional Comments helps with clearly communicating your intent, but more is needed when it comes to wording the actual feedback. Here are some suggestions to help make your written review feedback more constructive and effective.
Be curious
Assume a posture of genuine curiosity.
Don’t assume you have all the context. Try to catch yourself before jumping to conclusions and ask questions instead. For example, consider this comment:
Main component. That will
probably take a lot less code.
Regardless of the intention, this comment states as a fact that the bug could
(and should) be solved in the Main component. But maybe the author already
tried this, or there’s a hidden reason it won’t work?
Unless you’re very certain (and even if you are) consider asking a question from a place of genuine curiosity.
Main component? I wonder if that
would be a more straightforward fix and require less code.
Patient mentoring pays off exponentially
Knowledge shared with patience and kindness lands more deeply — and ripples out to others. They will reflect what they receive when they write their own reviews.
Leave actionable comments
Make sure it’s really clear how a review comment should be resolved. If there’s no obvious path forward, make sure that’s also obvious.
Combine similar comments
Don’t overload the recipient (or the tools) with lots of tiny comments. Batch similar issues into one comment — preferably with a patch. For example:
polish: Could we rename all m_X variables to just X? I see we decided
to use Hungarian Notation,
but that isn’t followed in this project.
For example, let’s do:
interface Wizard {
foo: string;
}
Instead of:
interface Wizard {
m_foo: string;
}
This is much nicer for both the reviewer and recipient, than writing/reading dozens of:
m_foo should be foo
m_bar should be bar
m_quackaroo should be quackaroo
Replace “you” with “we”
This comment is direct, but needlessly pointed. Even if we replace the label issue: with todo:, the phrase “you should” still places special focus on the person rather than the task. In someone’s mind, this kind of interpretation can happen almost automatically:
- “You should write tests for this.”
- “You should have written tests for this.”
- “Why aren’t there tests for this?”
- “You are to blame for the situation regarding the tests.”
This version is equally direct, but more collaborative. Writing tests is something that we do — whether it’s you, me, or someone else entirely.
People can’t read your mind. In verbal communication, tone of voice can convey collaboration and curiosity. In written communication, your “tone” comes only through your word choices.