Joseph Myers <jos...@codesourcery.com> 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’.