[webkit-dev] Fwd: coding style and comments

[Aaron Boodman]

On Mon, Jan 31, 2011 at 12:47 AM, Ryosuke Niwa <rniwa at webkit.org> wrote:
> How can we ensure that all comments are up to do date?  For example, suppose
> function A calls B, and B calls C.  Then in the call site of A, I comment
> "Because A does X, we do Y."  Now suppose for the moment that the behavior X
> of A is implemented by C.
> We then come back and modify C, thereby modifying the behavior X of A to X'.
>  We suddenly have a wrong comment in the call site of A and we need to fix
> it!  But how do we know that if the patch only changed one line in C?

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

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.

- a