I use commits for the largest bulk of explanation, particularly "why," which can be rather detailed and not of much interest to someone skimming the code rapidly.
Comments I use for pointers that are unlikely to bitrot and/or important to prevent error. Except for the most timeless design elements in a project, I do not commit long documentation.
Judging whether or not comments are permitted on the bitrot-ability of a piece of code seems hard to begin with, and even then a bit arbitrary. In this case, the whole comment would be just for that flag. So if someone really just gets rid of the flag but not the comment, especially on code like this, and that also passes code review then I think there are more pressing problems then bitrot.
> The way things stand, nobody would ever know why the signals are set up the way they are unless they trawled through 40,000 commits. Yes, 40,000: git log --oneline | wc -l.
git blame exists. 675eb72c285 src/runtime/os1_linux.go (Austin Clements 2014-12-19 16:16:17 -0500 417) var sa sigactiont
If it's really tedious to find relevant commit logs then I think the right answer is to improve the search process rather than compensate with more comments.
Another reason is that if you had a mistaken understanding when you made the commit and wrote up that understanding in the commit message, you're creating a greater risk of misleading future readers than if you'd put the writeup in a file which can itself be version-controlled.
I think the right place isn't necessarily code comments; separate internals documentation (in the same repo as the code) can be good too. Then the comment near the code can just be a cross-reference.
There is always a reason why things are 1) done and 2) done in this specific way and not another. It is also relevant if this is part of a larger change and it there are external dependencies on this commit. These things must be clear from the commit message.
> you're just doing janitor work
That makes it sound like janitorial work does not require complete commit messages which is why we sometimes see useless messages. There is always a reason why something was done and this can be documented.
A bug can be documented why it happened, why it was fixed in this specific way and not some other more obvious way, and what steps has been taken not avoid it from resurfacing. The same way a clean up can describe why others paths were not taken, why the new way is considered more clean (fewer lines, lesser complexity?) and how we know it does not entail functional changes.
The git tool is rooted in email, and commit messages look a lot like it. Pretend you are describing your patch over email to someone and it will be almost trivial to write.
Re: Email being an inaccessible silo: communities that use git-format-patch/git-am usually use mailing lists, which are archived, and subject lines have [PATCH] in them so searching needn't be difficult.
Nowadays that I use VS code with GitLens, each line of code automatically shows me its latest commit message, just hover that info and I have the date, author and a link to the changes which usually give some useful context to understand why and how some particular line was edited. Very useful!
Too many times have I seen well documented code only to later realize that the code was edited with no updates to the comments, now useless and a source of time waste...
Signals are tricky, temperamental beasts; exactly the sort of thing you'd want to have comments about in your code. The way things stand, nobody would ever know why the signals are set up the way they are unless they trawled through 40,000 commits. Yes, 40,000: git log --oneline | wc -l.
I'm all for giving a helpful description of why a commit was needed, but this is FAR too detailed for a commit message, and belongs in the CODE, which people will actually be reading while they debug an issue.
As for his other examples of bad commits, "Moved A to B" is not necessarily bad, unless there was a reason to do it other than to just rearrange where things lie. Same goes for "Add convenience functions" or "Code cleanup". If you're not fixing a bug or adding new functionality, you're just doing janitor work. And that doesn't require detailed descriptions.
Commit messages are to let people know in a concise way why you made the commit. Comments are to let readers know why you've done things in an unexpected way, or to describe things they're not expected to be familiar with, or tricky gotchas.