[webkit-dev] Fwd: coding style and comments

[Ryosuke Niwa]

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:
http://trac.webkit.org/browser/trunk/WebCore/editing/IndentOutdentCommand.cpp?rev=41034#L79

we're working around an issue in moveParagraph:
http://trac.webkit.org/browser/trunk/WebCore/editing/CompositeEditCommand.cpp?rev=41034#L737

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,
moveParagraph.

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.

- Ryosuke
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20110131/fc28e256/attachment.html>