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

[Dana Jansens]

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


>
> Thanks.
> _______________________________________________
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
> http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20120706/d938af93/attachment.html>