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 [email protected]
