[webkit-dev] Please include function-level comments in change log entries

[Ryosuke Niwa]

On Fri, Jul 6, 2012 at 11:42 AM, Dana Jansens <danakj at chromium.org> wrote:

> On Fri, Jul 6, 2012 at 1:05 PM, Dan Bernstein <mitz at apple.com> wrote:
>
>> It appears that lately most WebCore change log entires don’t include any
>> comments on individual functions. An overall description of the change at
>> the top of the change log entry is valuable, but it is no substitute for
>> describing the changes to each function. Good function-level comments are
>> useful both while reviewing a patch and while revisiting existing code.
>> Personally, I find that writing the function-level comments helps me a lot
>> in reviewing my own patches before I post them.
>>
>
> I find that the overhead of maintaining comments outside of the top of the
> changelog is excessive. Every time I change a patch in a non-trivial way
> during the review process, I must regenerate the changelogs.
> Copy/paste/edit the description at the top is not unreasonable.
>

Perhaps we need a better tool here. Re-generating per-function entries
while moving the rest of change log entry shouldn't be too hard.

Hand-merging my old changelog with the new one for each method becomes
> an egregious amount of work. And I don't see how it helps review more than
> a proper description at the top that mentions the methods of interest as
> appropriate.
>

I find it very useful during my reviews.

It's not necessarily useful to add comments to each function. For example,
if you're renaming a function A to B, and then there's no point in adding
per-function comments for each function that calls B.

On the other hand, if you're making a substantial change to some function
C, then it's definitely useful to see what has changed in C and why even if
that comment repeats, or preferably point to, some of the information in
the log description at the top.

Also note that your change log might be read by someone trying to figure
out why you made a particular change in one function 5 years from now. He
or she may not know the context in which the patch was created (because the
structure of the code would have changed so much). In such cases,
per-function comments are very valuable and save a lot of his or her time.

- Ryosuke
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20120706/9e799dc9/attachment.html>