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

[Maciej Stachowiak]

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.

Regards,
Maciej