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 what the underlying problems actually are, and so their suggested approach is 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 here 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 actual problem with the original comment, which is that 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 rather work with people who try to always think about giving actionable comments. I would rather 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 (I’m assuming it’s some UI text here), 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 sure I’m 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 certain 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 now 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 be learning to communicate better. This seems to be a common problem of seeking technical solutions to social problems that comes up a lot in the tech world.
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. What they do require is 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.
