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

[Maciej Stachowiak]

Starting a new thread, since this has wandered a fair bit off topic (and Eric had a good point that it's kind of a threadjack).

On Jul 6, 2012, at 12:54 PM, Per Bothner <per.bothner at oracle.com> wrote:

> The biggest annoyance I found is lack of class-level comments.  For example
> what is an Interpreter?  How many instances are there in the system?
> (I.e. is it a singleton class?  Is there one per window? One per thread?)
> What is the relationship to JSGlobalData, JSGlobalObject, RootObject.
> There are a lot of these classes, and it takes quite a bit of staring at
> the code to figure it out. Worse, it's hard to remember it all, so if I
> come back to the codebase after working on something else I have to
> figure out all out again: I might remember some aspects (like a class
> starting with JS is probably some kind of JavaScript object), but not
> a lot of other relationships and properties of the classes.

My recollection is that in past discussions, most folks were in favor of class-level comments that describe the purpose and nature of the class, particularly if not self-evident from the name. I think we'd likely take patches to take such comments. We also generally like "why" comments inside functions - comments that explain why something is done that way. 


What we don't really like is function-level "what" comments - ones that just restate what the code says. Stuff like this:

// increment reference count by one
refCount++;

Comments like this make the function longer and harder to read, without actually adding explanatory value.

In other cases, comments describe what a sequence of steps does where often a well-named function could achieve the same explanatory purpose. Or they describe a precondition or postcondition where often an ASSERT would be better.


Class-level comments don't really fall into these categories, and certainly the purpose of some of the objects you mention is not self-evident from the name (as with e.g. AffineTransform).

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. Perhaps we could include references to such diagrams in class comments too, if anyone was willing to maintain such diagrams for an extended period.


Regards,
Maciej