[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Using VC for change descriptions
From: |
Joseph Myers |
Subject: |
Re: Using VC for change descriptions |
Date: |
Tue, 9 Jan 2018 17:07:16 +0000 |
User-agent: |
Alpine 2.20 (DEB 67 2015-01-07) |
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
- Re: Using VC for change descriptions, (continued)
- Re: Using VC for change descriptions, Richard Stallman, 2018/01/07
- Re: Using VC for change descriptions, Joseph Myers, 2018/01/09
- Re: Using VC for change descriptions, Richard Stallman, 2018/01/14
- Re: Using VC for change descriptions, Joseph Myers, 2018/01/15
- Re: Using VC for change descriptions, Joseph Myers, 2018/01/15
Re: Using VC for change descriptions, Richard Stallman, 2018/01/07
- Re: Using VC for change descriptions,
Joseph Myers <=