[webkit-dev] Class-level comments in the source code

[Ryosuke Niwa]

On Jul 6, 2012 4:34 PM, "Maciej Stachowiak" <mjs at apple.com> wrote:
>
> On Jul 6, 2012, at 2:37 PM, Per Bothner <per.bothner at oracle.com> wrote:
>
> > On 07/06/2012 02:02 PM, Maciej Stachowiak wrote:
> >
> > [... reasonable stuff I fully agree with - but one question ...]
> >
> >> Documenting ownership and lifetime relationships is also useful. We
have tended to do that as diagrams separate from the code, since the places
where it is most needed tend to be complicated clusters of related objects.
> >
> > Wouldn't such diagrams be harder to keep up-to-date than comments?
>
> Not necessarily. When you change an ownership relationship, you may have
to update information about several classes, some of which may not have
their code directly changed in the patch that modifies ownership model. In
such cases, it would be easier to change one document than to find and
update all the affected places. And if you fail to find one of the relevant
places, you may end up with a false comment about ownership, which is more
dangerous than no comment at all. That being said, I have not seriously
tried either approach in WebKit so it's hard to predict which would be
better in practice.

I've seen deceiving comments like that in the past. Even for external
documentation, how do you suppose we keep them up to date?

I'm frequently annoyed by WebKit wiki pages providing false information
already (of course, I try to fix them as I encounter).

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