> On Jul 5, 2018, at 10:44 AM, Florian Weimer <f...@deneb.enyo.de> wrote:
>
> * Richard Kenner:
>
>>> GCC ChangeLogs don't record the purpose of the change. They say what
>>> changed,
>>> but not why.
>>
>> That depends on how you define "purpose". Let's take a random entry,
>> from a 1999 change of mine:
>>
>> * expr.c (expand_expr): If ignoring reference operations,
>> just expand the operands.
>> (expand_expr, case COMPONENT_REF): Refine test for when need
>> to use bitfield operations or pointer punning.
>>
>> This indeed doesn't say why the change was made (though later policy
>> did tend to at least suggest adding PR numbers), but does say, in some
>> detail, what was changed. You can't get that informtion from the current
>> state of the code. You could indeed derive it from the diff itself, but
>> that's work and having a short summary is very helpful.
>
> But this is against GNU policy for ChangeLog entries. Explanations of
> the change should go into the source code, as comments.
>
> (Of course, this policy is problematic if you *remove* code.)
More than that: comments in code normally explain what the code does today.
They do not explain (and should not) how the current code differs from what was
there before. So they give no insight in the reason for the change, except
only very indirectly and then only some of the time.
paul
