[webkit-dev] Fwd: coding style and comments
rniwa at webkit.org
Mon Jan 31 01:22:59 PST 2011
2011/1/31 Konstantin Tokarev <annulen at yandex.ru>
> 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
I don't see how that can substitute my comment that "Because A does X, do
Y". Saying "do Y because we call A" isn't useful at all here.
But if A is API function, its behavior (what C does) should be described in
> place anyway
Okay, let me give you a more concrete example. In this case:
we're working around an issue in moveParagraph:
Now, moveParagraph is a very complicated function that does a million of
things depending on the structure of DOM and 5 arguments, and it's mutually
recursive with 2 other editing commands ReplaceSelectionCommand and
DeleteSelectionCommand, both of which depend on many other editing commands
and the rest of WebCore.
As a result, it's virtually impossible to describe the complete behavior
of moveParagraph. And if we changed any one line in WebCore/editing, there
is a significant chance that we're changing the behavior of either
ReplaceSelectionCommand or DeleteSelectionCommand and subsequently,
This is just a tip of an iceberg. I can give you hundreds of examples where
you can't describe the behavior of a function completely, and yet you need
to be concerned with it in call sites.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the webkit-dev