[webkit-dev] Fwd: coding style and comments

[Maciej Stachowiak]

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.

Regards,
Maciej