[webkit-dev] Fwd: coding style and comments

[Konstantin Tokarev]

31.01.2011, 11:47, "Ryosuke Niwa" <rniwa at webkit.org>:
> 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?
>
> - Ryosuke
>

You can document A as function calling B, B as function calling C, and keep documentation of C up to date when it's behavior changes

But if A is API function, its behavior (what C does) should be described in place anyway

-- 
Regards,
Konstantin