alt Hacker NewsI often write PR descriptions, in which I write a short explanation and try to anticipate some comments I might get. Well, every time I do, I will still get those exact comments because nobody bothers reading the description.
Not to say you shouldn't write descriptions, I will keep doing it because it's my job. But a lot of people just don't care enough or are too distracted to read them.
Replies
What is the overall practice in the team? Does everybody write good descriptions and nobody reads them, or only a few of them write good descriptions and nobody reads them?
Because if it's the latter, there's your problem: even those who write good descriptions do not expect a change request to have one, so they don't bother looking.
This is a hill I’m going to die on, but I find 9/10 times people use the pr description for what should have been comments. “Git blame” and following a link to a pr is inferior ux to source code comments.
The North Star of pr review is zero comment approvals. Comments should not be answered in line, but by pushing updates to the code. The next reader otherwise will have the exact same question and they won’t have the answer there.
The exception being comments which only make sense for the sod itself but not the new state of the code. IME that’s ~10%.
I have bought my tombstone.
After I accepted that, I then tried to preempt the comment by just commenting myself on the function/class etc that I thought might need some elaboration...
Well, I'm sure you can guess what happened after that - within the same file even
At my place nobody reads my descriptions because nobody writes them so they assume there isn't one!
Yeah, I've definitely found that nobody reads more than maybe 10 words of the PR description.
I've also never seen anybody but myself write substantial PR descriptions at my previous 4-5 jobs
I just point people to the description. no need to type things twice.
For many of my PR and issue comments the intended audience is myself. I find them useful even a few days later, and they become invaluable months or years later when I'm trying to understand why the code is how it is.