Conventional Comments
conventionalcomments.org
Conventional Comments
1–10 of 74 posts
Re: Conventional Comments
#2Very much inspired from Conventional Commits, this expands the idea to review comments.
At GitLab, we are a fully remote organization so we do a lot of written communication. This has been a great pattern for improving readability and the content of review comments. Plus, it's machine parseable which means we could easily query and aggregate these comments in the future!
Re: Conventional Comments
#3I get the ones where you're suggesting alterations to the code, but having "praise: You did great here" or "chore: Could you run the tests" sounds weirdly robotic to me
Re: Conventional Comments
#4This sounds great! I have often felt the lack of a common language to specify for each review comment if an action is expected. This looks like this convention solves the problem with a nice Schelling point.
nitpick (non-blocking): I won't use the "praise:" keyword as it feels robotic. Praise should feel spontaneous and authentic. But I love the general advice of trying to have at least one praise comment per code review.
Re: Conventional Comments
#5I get the ones where you're suggesting alterations to the code, but having "praise: You did great here" or "chore: Could you run the tests" sounds weirdly robotic to me
[deleted]
Re: Conventional Comments
#6Only tangentially relevant:
I hate the word 'nitpick' (bad experience with small insects - thinking about nits makes me itch), but I don't know any other word for these "small, trivial, but necessary changes." Does anyone have alternative words they use in reviews instead?
Re: Conventional Comments
#7Only tangentially relevant: I hate the word 'nitpick' (bad experience with small insects - thinking about nits makes me itch), but I don't know any other word for these "small, trivial, but necessary changes." Does anyone have alternative words they use in reviews instead?
papercut?
Re: Conventional Comments
#8I get the ones where you're suggesting alterations to the code, but having "praise: You did great here" or "chore: Could you run the tests" sounds weirdly robotic to me
It reminds me of the Elcor from Mass Effect. The problem they face is similar to textual comments: Elcor cannot emote in a way that's detectable to non-Elcor, so when communicating with alien races such as humans, they have to prefix every utterance with an emotional descriptor. E.g., "Pleased greeting: Human, it is always good to see your kind."
Re: Conventional Comments
#9I like these ideas a lot and if I was mentoring someone in leaving feedback I would strongly encourage providing examples along with suggestions. I like that the "suggestion" label provides a little mental prompt to do that. The easier it is to take action on feedback the better. A diff patch or PR would be ideal.
In the office environment where I find I'm often using MS Word with track changes to collaborate (horrors!) I'd much rather a reviewer make a tracked change and leave a comment in the document then send me an email.
The flip side is reducing friction for reviewers by making your document easily accessible, and easy to change and comment on, pays dividends.
Re: Conventional Comments
#10Only tangentially relevant: I hate the word 'nitpick' (bad experience with small insects - thinking about nits makes me itch), but I don't know any other word for these "small, trivial, but necessary changes." Does anyone have alternative words they use in reviews instead?
"minor"?