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

[Ryosuke Niwa]

On Fri, Jul 6, 2012 at 1:51 PM, Per Bothner <per.bothner at oracle.com> wrote:
>
> Documenting what a function/method does is sometimes useful,
> but what is really important is documenting what (an instance of)
> a class *is* and (preferably) how it relates to other objects.


For some classes, yes.

On Fri, Jul 6, 2012 at 2:02 PM, Maciej Stachowiak <mjs at apple.com> wrote:
>
> 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.

...

> 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).
>

I'd argue that we should still strive to make class names self-explanatory
as much as possible, and use comments as the last resort.

I've found that our culture of not adding comments have given me a pressure
to think really hard to come up with better class names rather than going
with vague names with explanatory comments. In some cases, it made me
realize that the particular object relationships I had in my mind was not a
good design and made me come up with a new design that involved
easier-to-understand classes.

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