[webkit-dev] Comments in the code (Was Please include function-level comments in change log entries)

[Ryosuke Niwa]

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

> On Fri, Jul 13, 2012 at 1:56 PM, Ryosuke Niwa <rniwa at webkit.org> wrote:
>
>> On Fri, Jul 13, 2012 at 5:57 AM, Stephen Chenney <schenney at chromium.org>wrote:
>>
>>>  I don't doubt there are poor comments, both outdated and useless.
>>> That's a reviewing failure. You have simply highlighted the fact that any
>>> standard for comments requires reviewer attention. Hence "cost of
>>> maintaining comments".
>>>
>>
>> I don't know how to review a patch and make sure all relevant comments
>> are updated.
>>
>> As I have illustrated before, you can be modifying a function X, then a
>> completely random function A which calls B that in turn calls C that in
>> turns D ... that in turn calls X may have a comment dependent on the
>> previous behavior of X without ever mentioning X. How am I supposed to know
>> that there is such a comment?
>>
>
> How is that different than the same question but replace "comment" with
> "behaviour"? In both cases A is no longer doing what it expected. Something
> is going to break, and A will have to be fixed/updated, comment included.
>

Not necessarily. First off, the behavioral change may not have any user
visible behavioral change, or that while X behaves differently, it doesn't
affect the way A works due to some other changes in the same patch. Or it's
possible that new behavior of A is expected and desirable but the change
was made at much lower level and affected hundreds of other functions.

- Ryosuke
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20120713/62a67885/attachment.html>