I’ve seen this idea called conventional comments come up a few times lately, and while the intent is admirable—to improve communication in a text environment such as code review comments—I don’t think the author has thought through the underlying problems, and so their suggested approach seems little more than an attempt to sugar coat a lack of communicational awareness.
On machine readability
I’m ignoring the argument about machine readability here. I haven’t found the need to do this myself, but if you have that need, this might be good for that purpose.
Since the author doesn’t lead with that, I’m discussing only their main argument.
Let’s start with their first example. They argue…
Comments like this are unhelpful…
“This is not worded correctly.”
And I wholeheartedly agree, but their suggested solution is to prefix the comment with a label so that “the intention is clear and the tone changes”.
”suggestion: This is not worded correctly.”
I don’t think that actually changes the tone. It seems merely to shift it into a passive-aggressive register. “It’s just a suggestion, you don’t have to do anything about it.” Then why are you saying it’s “not worded correctly”? That doesn’t solve the real problem with the original comment: the author didn’t explain why it wasn’t worded correctly or suggest a solution.
In the next section, they suggest that the label “prompts the [author] to give more actionable comments”, which again I agree with the intent, but not the method.
I would prefer to work with people who always try to think about giving actionable comments. I would prefer to work with people who consider how their writing might be read, and not write things like “This is not worded correctly”. It’s very easy to be a jerk; it takes empathy and effort not to be.
Depending on what’s actually being commented on—say for example this was about some copy text in a UI, or some documentation—better comments might be, “There’s a grammatical error here. You used ‘it’s’ instead of ‘its’ in this sentence.”, or “The phrasing here is a bit ambiguous because of the unresolved pronoun ‘it’, maybe we could be more explicit about what we’re referring to.”
Wait, I’ve heard that voice before
I’m probably not the first person to notice this. Another problem with this scheme is that anyone of a certain age who plays video games is going to be reminded of a particular character from a certain game whenever they read statements that look like this:
Query: Can I kill him now, master?
Suggestion: Perhaps we could dismember the organic?
Commentary: I say we blast the meatbag and save you the trouble, master.
Those are a small number of quotes from the character HK-47, from the video game Star Wars: Knights of the Old Republic. HK-47 is a sociopathic assassin droid built by a Sith Lord1.
I can’t help but read text written in that style in the voice of HK-47. So, while the author’s intent was to be more clearly understood, they’ve inadvertently layered on a nice helping of sociopathic assassin droid.
Clearly, this is a problem on my end as the reader. I shouldn’t draw those associations into what I’m doing now, but it comes up just the same, unbidden.
Learning to communicate better
I think instead of prefixing labels onto statements, we should learn to communicate better. This seems to be a common problem in the tech world: seeking technical solutions to social problems.
The author seems to even realize this when they added a “best practices” section at the bottom of the page with this list:
- Mentoring pays off exponentially
- Leave actionable comments
- Combine similar comments
- Replace “you” with “we”
- Replace “should” with “could”
Those suggestions don’t need a labelling system. They require more thought about how something might be received, and most of all empathy, which I frequently find lacking in heated technical discussions. No simple trick is going to solve that problem.
Footnotes
-
There’s another group of people who will be reminded of the Elcor from the Mass Effect series, also from Bioware. They at least doesn’t have the negative connotations that HK-47 has.
