Conventional Communication

At my day job I review a lot of other people's work, in the form of code reviews or design (and other) documents. A few years back a coworker whose code I was reviewing requested, rather insistently, that I start using conventional comments when doing code reviews. They also messaged it out to the team, though more as a practice suggestion and not a proposed change to the team's process.

I internally shrugged the request off, as they were a junior engineer still working through their personal relationship to feedback — as we all do. I don't think many people are raised with the education necessary for internally de-personalizing feedback, analyzing your own behavior, synthesizing the given feedback with your own understanding of "the world", and thanking the other person for their gift, regardless of your orientation towards that "gift". It's complicated stuff and most of us, myself included, take years to adjust our reactions accordingly.

They were insecurely interpreting my code review comments as "having a tone", I think, and wanted me to be "nicer". I don't leave unconstructive comments, and as time has gone on I've learned to basically not ask open-ended questions without offering answers, lest the other engineer shrug "I couldn't think of a good solution".

It's almost a truism that communication between two people involves both parties, but so easy to forget when you're focusing on one of them. Regardless of where my coworker is at, it doesn't hurt me to adopt a different communication style. At worst its a mild annoyance, but at best it structures my information with more accessibility. For this reason I've adopted the convention to this day.

Convention Rationale

I find it funny that the conventional comments website gives so little rationale for adoption.

By simply prefixing the comment with a label, the intention is clear and the tone dramatically changes.

The double-edged sword of communication is still at play 😆. All language is a game, subject to the shared context of the players. Intention is dependent on the mind of the speaker and the mind of the listener aligning. Prefixing "this needs unit tests" with "suggestion: this needs unit tests." does not make the reviewer's intention any clearer — perhaps they're saying this condescendingly, or perhaps they're saying it matter-of-fact.

Regardless, I choose to assume good faith, and so should you. I'll provide the extra comment information and hope it helps those that need it.

Communication Bandwidth

Code and doc review comments suffer from similar issues that text messaging suffers from — text as a medium doesn't allow for the additional context of tone-of-voice, cadence, speed, etc. I find myself falling into the same texting/Slack pattern of appending an emoji at the end of the sentence to try and give some tone, much like the Elcor^[1].

This feels of a similar quality as the intention behind conventional comments, an attempt as the speaker to reach your hand out a little farther, to reach listeners with less range.

Related

I've been trying out conventional commits lately. I think its overall trying to serve a different purpose, though

Communicating the nature of changes to teammates, the public, and other stakeholders.

has a similar aim.