[webkit-dev] Fwd: coding style and comments

Maciej Stachowiak mjs at apple.com
Mon Jan 31 19:06:30 PST 2011

On Jan 31, 2011, at 5:48 PM, Aaron Boodman wrote:

> On Mon, Jan 31, 2011 at 5:23 PM, Ryosuke Niwa <rniwa at webkit.org> wrote:
>> On Mon, Jan 31, 2011 at 4:54 PM, Aaron Boodman <aa at chromium.org> wrote:
>>> It seems like the one line patch to C just broke A. It had a
>>> dependency on the behavior of C that was worth documenting. Now you
>>> have changed C and the behavior of A is probably wrong (or at least
>>> wasteful).
>> Not necessarily. X' might be better a behavior and Y might no longer be
>> needed because of that.
> That is exactly my point. Either way the one line change leaves orphan
> code. Having a comment just improves your chances of finding it
> (assuming the comment references the depended-upon code).
>>> If you had the comment, at least a grep of the source would have found the
>>> dependency and alerted you that it was worth looking at this call site.
>> I don't think so.  How do I know that modifying C would have changed the
>> behavior of A?
> To be specific, I'm talking about this situation:
> void doA() {
>  // We don't need to frobulate here because doC() already did that.
> }

If previous frobulation is a precondition of doA, that's better expressed as an ASSERT than as a comment. That way, if someone breaks the precondition, they'll find out when they test, whether or not they think to search for related comments.

I <3 asserts as a way to document preconditions.


More information about the webkit-dev mailing list