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

[Ryosuke Niwa]

On Fri, Jul 6, 2012 at 11:34 AM, Per Bothner <per.bothner at oracle.com> wrote:

> On 07/06/2012 10:05 AM, Dan Bernstein 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.
>>
>
> You forget there is a WebKit policy of not writing comments
> or otherwise documenting the code.
>
> Or at least that's what it looks like. :-(


Dan is talking about per-function descriptions in ChangeLog entries, not in
the source code.

Indeed, we try to avoid adding comments as much as possible since comments
tend to get out-of-date very quickly, we don't want to be spending all our
time updating comments. Instead, we try to refactor code so that code is
self-evident or add assertions to codify the comments.

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