Re: Circumstances in which ChangeLog format is no longer useful

[Joseph Myers]

On Sat, 5 Aug 2017, Ludovic Courtès wrote:

> I think this part of the change log rationale still holds (info
> "(standards) Change Log Concepts")
> 
>      There's no need to describe the full purpose of the changes or how
>   they work together.  However, sometimes it is useful to write one line
>   to describe the overall purpose of a change or a batch of changes.  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.

There are cases where explanations in the code are relevant.  But those 
serve different purposes and are to be understood in different contexts.  
The comments in the code should explain the current version of the code 
and should be understood in the context of that version.  They don't need 
to explain what was different in some past version of the code, or why 
that past version of the code was incorrect or inferior, unless a reader 
of the current code might think it odd on first reading and expect it to 
be the different (older, incorrect) version instead.

Whereas the commit description (=~ mailing list posting proposing and 
justifying the patch for inclusion, in my view) needs to explain, relative 
to the old version of the code, why the new version is better.  And 
sometimes there may be no plausible place to attach a comment, e.g. if the 
patch is removing code not adding it (but it may still need detailed 
reasoning about why the removal is desirable and safe and a detailed 
discussion of how it was done).  Or if it is changing code from a 
less-natural (now) form to a more-natural form, code doing things the 
natural and expected way may not need a comment to say why it's doing so, 
but a detailed explanation of the context in which the old form made sense 
and how that no longer applies is still appropriate for the commit 
message.

Furthermore, for many pieces of software any bug or new feature will be 
accompanied by testcases that would fail if the change were reverted, and 
seeing what tests fail if a change is made can be a useful way for 
developers to understand what is or is not essential about the current 
implementation of a feature.

That is: I'm not proposing to remove any requirements for comments e.g. 
explaining the semantics of a function, and if there are nonobvious things 
about why some feature of the code is required, I fully encourage comments 
explaining those, and design comments that explain high-level design and 
are kept up to date as that design changes are to be encouraged as well.  
But I do *not* encourage comments that describe how something was changed 
(that belongs in the commit message) - as opposed to (good) comments of 
the form /* This case can occur when X.  See test-something.c.  */ (or 
"See bug 12345.").

> There’s also the positive side-effect of writing a change log: it’s for
> me an opportunity to review what I’m going to commit.

People should certainly review what they are going to commit, but I think 
reading the change in detail *without* writing a ChangeLog entry is better 
for that.

-- 
Joseph S. Myers
address@hidden