Re: Circumstances in which ChangeLog format is no longer useful

[Ludovic Courtès]

Joseph Myers <address@hidden> skribis:

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

Understood.  Sounds reasonable to me, as long as we make it clear that
commit logs are no substitute for explanations in the code, that they
serve a different purpose, as you wrote.

Thanks,
Ludo’.