On Sun, 7 Jan 2018, Richard Stallman wrote: > > Furthermore, comments in the source code about why it does something are > > comments explaining things that are nonobvious about the current state of > > the source code, e.g. why a particular special case is needed. They are > > not about how it got there. > > They aren't?? Do you mean, you think GNU maintainers are not carrying out > what the coding standards say?
I see nothing in the standards that says the comments should be about the path-dependent aspects of the sources (why and how they changed to get to their present state), as opposed to their current state. The most relevant text seems to be: For changes to code, there's no need to describe the full purpose of the changes or how they work together. If you think that a change calls for explanation, you're probably right. Please do explain it---but please put the full explanation in comments in the code, where people will see it whenever they see the code. For example, ``New function'' is enough for the change log when you add a function, because there should be a comment before the function definition to explain what it does, how to call it, and so on. I would consider a comment explaining e.g. "The check for X is needed because of case Y." to be in full conformance with the standards - indeed, to be preferable to one that says "The check for X was added to fix a bug involving case Y." (people reading the code ideally shouldn't need to know whether there was a previous version missing that check and with an associated bug). If other code changes so that the check is needed instead for case Z but not for case Y, the first example can trivially be updated accordingly, but changing the latter to "The check for X was added to fix a bug involving case Y, but is now needed for case Z instead." makes it worse. -- Joseph S. Myers [email protected]
