Re: Using VC for change descriptions

[Joseph Myers]

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
address@hidden