Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Conventional Comments

conventionalcomments.org

Post reply on HN
Print view View original

31–40 of 74 posts

Re: Conventional Comments

#31

Post by MAGZine »

derefr wrote: post #16
jevgeni wrote: post #11

This is just a hack to the problem that most people can’t write and don’t know how to write something that’s valuable to the reader. Just put some thought and care into the comments.

> most people can’t write and don’t know how to write something that’s valuable to the reader ...yes? And? 99.999% of people's comparative advantage is not in their writing ability. Add to this that learning to write to a quality level required for effective, efficient communication, is a far higher burden to place on someone, than the level of fluency required for basic exchange of information; especially for people…

I abhor the idea that learning to communicate effectively is "a waste of time." Rather than try to avoid learning an incredibly useful skill, people who CAN'T communicate effectively could use code review as a learning/skill building opportunity.

If I switch "communicate," with "program," do you still think it's a good argument that people shouldn't obtain any more programming skill than the most rudimentary level, because it would be a waste of time?

Conversely, I think clear communication will probably help you write better, clearer, more concise code.

It's a win-win.

Re: Conventional Comments

#32

Post by mirimir »

derefr wrote: post #16
jevgeni wrote: post #11

This is just a hack to the problem that most people can’t write and don’t know how to write something that’s valuable to the reader. Just put some thought and care into the comments.

> most people can’t write and don’t know how to write something that’s valuable to the reader ...yes? And? 99.999% of people's comparative advantage is not in their writing ability. Add to this that learning to write to a quality level required for effective, efficient communication, is a far higher burden to place on someone, than the level of fluency required for basic exchange of information; especially for people…

> Most people intuitively know that learning to write more effectively isn't the best use of their time, and so most people don't try.

Funny. I decided that about coding, perhaps 40 years ago.

But I did later learn enough SQL to crunch data. And I've picked up enough bash to automate stuff.

Re: Conventional Comments

#33

Post by brailsafe »

manoDev wrote: post #29

It seems I disagree w/ many points. > - Leave actionable comments > suggestion: This is not worded correctly. > Can we change this to match the wording of the marketing page? If I already know how it should be, I prefer to quote it right away and save work, instead of asking and leaving room for misinterpretation. Asking also seems dishonest if I'm not truly inviting a discussion. I would still add a rationale so oth…

Agreed. My thought was at least that the tone of the chosen rhetoric seemed sort of passive-aggressive or meek. I tend to prefer use of phrases like "suggestion: This seems like it would be improved by more closely resembling the other marketing pages". That said, asking a question is a communication tactic that is supposed to illicit a response, however disingenuous it may be.

Re: Conventional Comments

#34

Post by nine_k »

manoDev wrote: post #29

It seems I disagree w/ many points. > - Leave actionable comments > suggestion: This is not worded correctly. > Can we change this to match the wording of the marketing page? If I already know how it should be, I prefer to quote it right away and save work, instead of asking and leaving room for misinterpretation. Asking also seems dishonest if I'm not truly inviting a discussion. I would still add a rationale so oth…

Whatever you may think, people do see code reviews as conversations, and do take comments personally deep inside, even if they try hard to avoid this in the name of professionalism.

Rather than forcing people to exercise self-discipline while reading, it's nicer to exercise it yourself, and write comments in an impersonal way. Assuming that the reader is as smart as yourself just follows logically from the idea of peer review.

This is what I got from about 10 years of doing code reviews, which sometimes needed to be scathing by nature; to induce the desirable changes you've got to genuinely sound like you're acting in the author's best interests, not just do so.

Re: Conventional Comments

#35

Post by mgkimsal »

Why the 'we' if 'we' aren't going to do it, but I am?

I've had one interesting/productive 6 month engagement with a team where there were some of these comments, but sometimes... someone would actually just make the change in the branch. It saved time, let them get things "the way they wanted" and was generally agreeable to most on the team.

Someone making a change in 'my' branch wasn't an affront - it was a degree of collaboration. It was almost always preceded with a message of "hey, I see a small issue here - I'm gonna throw a small patch on it - let me call you after to discuss" or followed up with "hey - fyi - I saw a small bug and did a small patch/test - do you have a few minutes to talk at 3 about it?"

And... I would do the same with them, when warranted. It cut down on the delays and let people "take ownership". In the 'wrong hands', I'm sure it could get politically ugly, but no more so than a lot of passive-aggressive comments and blocking/nitpick stuff that holds things up unnecessarily.

One thing that was expected (and made it easier) was that whenever you did that (formal or informal review) you were expected to have pulled the code, installed/run the tests locally, run the code, and verified tests ran before you pushed anything back. A note saying "this doesn't seem right" carries different weight from someone giving it a 2 minute glance vs someone who's actually run that code and seen what you've seen. Yes, I know that often you can spot issues without running the code, but... not always (or, if you see the totality of the code in-situ, vs just diffs, you have more context).

Re: Conventional Comments

#36

Post by nine_k »

brailsafe wrote: post #33
manoDev wrote: post #29

It seems I disagree w/ many points. > - Leave actionable comments > suggestion: This is not worded correctly. > Can we change this to match the wording of the marketing page? If I already know how it should be, I prefer to quote it right away and save work, instead of asking and leaving room for misinterpretation. Asking also seems dishonest if I'm not truly inviting a discussion. I would still add a rationale so oth…

Agreed. My thought was at least that the tone of the chosen rhetoric seemed sort of passive-aggressive or meek. I tend to prefer use of phrases like "suggestion: This seems like it would be improved by more closely resembling the other marketing pages". That said, asking a question is a communication tactic that is supposed to illicit a response, however disingenuous it may be.

Asking a question makes the reader find the answer, and thus understand it, and the reasons for it.

Also, sometimes the answer won't be the one you'd expected.

Re: Conventional Comments

#37

Post by nine_k »

jchw wrote: post #27

I agree with the vast majority of this, but I have a bad reaction to “praise” and the idea that you should try to have one per review. I hate praise that feels forced, and it seems like this kind of practice would make it seem quite forced. I feel you could just say something like “good idea” and it would be fine without the prefix. Especially if your review tool of choice has a concept of actionable vs non-actionabl…

Indeed! The praise should be genuine (the author finally fixes a bothersome issue, comes up with a particularly nice solution, etc), and compact. Often a :thumb-up: is totally sufficient.

Re: Conventional Comments

#38

Post by JimDabell »

leipert wrote: post #23
GGfpc wrote: post #3

I 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

Disclaimer: I am a coworker of the author. I like Praise. We don’t give it often enough and if someone does something awesome like simplifying complicated tests, removing dependencies or works smart and not hard, it is due. While the conventional comments give a nice framework, nothing stops someone from adding a cheerful gif to the body of that praise. Even on larger reviews it is nice if you scroll through 10 nitpi…

I would strongly dislike being a recipient of this "praise". The thought of all of my co-workers following this rule when reviewing my merge requests makes my skin crawl. You can see from the rest of the thread that other people have a negative reaction to it too. It's nice that you enjoy it but the same does not hold true for everybody. Is there a way for somebody working with you opting out from it or are they given no choice in the matter?

Re: Conventional Comments

#39

Post by souldzin »

jchw wrote: post #27

I agree with the vast majority of this, but I have a bad reaction to “praise” and the idea that you should try to have one per review. I hate praise that feels forced, and it seems like this kind of practice would make it seem quite forced. I feel you could just say something like “good idea” and it would be fine without the prefix. Especially if your review tool of choice has a concept of actionable vs non-actionabl…

> I hate praise that feels forced, and it seems like this kind of practice would make it seem quite forced.

This is a really good point.

Yeah, the `praise` comment is a call to find something to sincerely praise. If you can't find anything to praise (which is probably a warning sign that your head isn't in a happy place) don't leave a `praise`.

I updated the description with a little warning about this. What do you think? https://gitlab.com/conventionalcomments/conventionalcomments...

Re: Conventional Comments

#40

Post by themodelplumber »

Dream: Can we please get this on YouTube. User comments there are a disaster and they're making the entire platform worse.

Thank you for making this...and to the naysayers, suggestion: Do it better or stop blocking. This is miles better than doing nothing. And downvote, like always, if it makes you feel better...

Post reply on HN