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.
Conventional Comments
11–20 of 74 posts
Re: Conventional Comments
#12When leaving review comments our internal system is to use a blocking/non-blocking flag along with the classic three RFC keywords (MAY/SHOULD/MUST - often in bold) as two examples:
You MAY wish to improve readability here by binding these values to a local variable
We're using string building in this query with user input we MUST not allow any SQL injection routes.
Re: Conventional Comments
#13Only 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?
I wouldn't say nitpicks are necessary changes in most circumstances - they are really soft suggestions about very fine details, I tend to describe them with optional non-blocking comments. Nitpick is a really good term for them but "aesthetic" might work as an alternative, there isn't a huge glut of words in that realm though.
Re: Conventional Comments
#14I've started doing something like this naturally. I felt the need to communicate it could be improved but the code per se is not wrong. I started using suggestion, optional, minor, etc.
This seems like a formalization of what I had in mind, thanks
Re: Conventional Comments
#15this is a conventional comment
Re: Conventional Comments
#16This 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 for whom English (or whatever language is being used) is a second language.
Taken together, this implies that for most people, learning to write well—i.e. learning the skill that, having possessed it, would make you into a competent essayist—would be a waste of time. Just like learning abstract mathematics would be a waste of time. (And I say that as a professional author!)
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.
This "hack" is far less costly, and therefore far more likely to get adopted by these people, and therefore far more likely to actually improve the experience of reading the average communication in a large software project (which tends to involve people of varying communication levels.)
Re: Conventional Comments
#17I 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
Yeah, those in particular fall flat. If you want to praise, you should do so, and it should be clear in your statement. If it needs the descriptor, the descriptor won't help. I'd suggest s/praise/note. And s/chore/request. Just because it sounds more polite.
Re: Conventional Comments
#18This 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 gains in productivity have come from simplifying or automating away common tasks:
* Text editors spell-check your writing (just put more care into your writing!)
* Garbage-collected runtimes,or compile-time memory proofs prevent common memory errors (just write your C more carefully!)
* Machinery and power tools allow one to perform the same physical tasks more quickly (just put your back into it!)
* Agriculture allows one more reliable sources of nutrition & calories (just get good at hunting & gathering!)
Humans have a finite amount of "thought and care" to put into things. If there's a framework that allows for more rapid and reliable software development, with less thought and care spent, that's great. That thought & care can go into something more productive.
Re: Conventional Comments
#19This 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.
>This is just a hack to the problem that most people can’t write
But that is exactly what we need! It will always be easier to change the computers than to change the people. If we could replace all of the people with clones of von Neumann, most development practices (and UX) research would become irrelevant.
Re: Conventional Comments
#20I'm guessing this is about Code Review comments?
I always assume my comments on others' PRs (and other people's comments on my Code Reviews) are "suggestions (non-blocking)", unless indicated otherwise. Shouldn't that be the default, really?