Comment by skrebbel

I really like putting context into commits, not into code comments. The reasoning is pretty simple: Comments aren't checked. I might write "This is done this way because John Doe suggested it, it's much more efficient this way", and then someone else changes the code to be buggy, wrong, and slow. Now, the comment is explaining behavior that is no longer there, and wrongly suggests that the code does/means something it doesn't.

Another argument is comments-as-noise, as I would call it. The more "unnecessary" comments you write, the more core developers (who write and read most of the code), will learn to ignore comments. Then, critical comments like "Be careful not to call this when XYZ isn't initialized yet, unless you don't mind ABC happening" are ignored, and ta-da! comments are now useless.

Commit messages are attached to specific changes. If I want to know why a line of code is the way it is, I can git blame it, and see which commit is to blame, together with issue numbers, authors, maybe reviewers, context, history, etc.

Should there be a comment briefly explaining this patch? Probably. But the commit message should add the other context.

> What's the downside to having a 2 to 3 line comment above a constant in a C file?

That the code gets changed in the future such that the comment is a lie[1]. This happens with shocking regularity. Comments sound like a great idea until you deal with them in a long term maintenance situation.

As a corrolary, they also increase the cost of maintenance because if you end up doing refactoring that makes the comments a lie, it's never acceptable in review to just remove them. People expect you to write the same kind of treatise that the original author did. And original authors are horrifyingly verbose. All those doxygen crumbs you're leaving only act to confuse and irritate the pour souls coming after you.

Code is code. It should explain itself. If it does not, comments should do the absolute minimum needed (c.f. citing the relevant section in the ISA reference by number in this case) to rectify that.

[1] c.f. Guy Steele: https://softwarequotes.com/quote/don-t-get-suckered-in-by-th...

A lot of developers think code should be self-documenting, which I fully agree with. Unfortunately though I don't think I've ever worked on a project that was actually self-documented, even though that is what the leads wanted.

But this works as intended? The code isn't cluttered with documentation, that doesn't necessarily makes sense when reading the code, but by reading the commit, one can understand why the code was written like that.

Huh? Quoting a bit more from the article:

> [W]e find this in ARM.cpp:

> trapInstr = {0xd4, 0xd4, 0xd4, 0xd4};

The only thing left to explain is that the trap instruction is used as padding, but you can’t tell from here if that’s obvious or not. Opening the actual code[1], we see that the occurrences of trapInstr are all along the lines of

> void ARM::writePlt( /* ... */ ) {

> /* ... */

> memcpy(buf + 12, trapInstr.data(), 4); // Pad to 16-byte boundary

which isn’t the absolute best, but seems clear enough (if of course you know what a PLT is, which you should if you’re writing a linker).

I do think this merits an explanation that we’re using (what’s intended to be) a trap because the traditional option of using a nop makes ASLR less effective. But then the commit message you’re quoting doesn’t mention that either.

[1] https://github.com/llvm/llvm-project/blob/b20c291baec94ba370...

I think it's a human thing. The Torah is succinct; The Talmud has a lot to say about it. For a large codebase, the comments would be huge, and also I think distracting.

In fact, as a former code auditor I can say that comments at times make bug finding harder -- they frame you up a certain way. I definitely preferred to audit without comments.

Anyway, there are definitely valid reasons. I think the commit log or dev notes files are generally preferable, especially when combined with good naming.