Comment by ajross

> 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...