<p><br>
On Jul 6, 2012 4:29 PM, "Maciej Stachowiak" <<a href="mailto:mjs@apple.com">mjs@apple.com</a>> wrote:<br>
><br>
><br>
> On Jul 6, 2012, at 2:18 PM, Ryosuke Niwa <<a href="mailto:rniwa@webkit.org">rniwa@webkit.org</a>> wrote:<br>
><br>
>> On Fri, Jul 6, 2012 at 1:51 PM, Per Bothner <<a href="mailto:per.bothner@oracle.com">per.bothner@oracle.com</a>> wrote:<br>
>>><br>
>>> Documenting what a function/method does is sometimes useful,<br>
>>> but what is really important is documenting what (an instance of)<br>
>>> a class *is* and (preferably) how it relates to other objects.<br>
>><br>
>><br>
>> For some classes, yes.<br>
>><br>
>> On Fri, Jul 6, 2012 at 2:02 PM, Maciej Stachowiak <<a href="mailto:mjs@apple.com">mjs@apple.com</a>> wrote:<br>
>>><br>
>>> On Jul 6, 2012, at 12:54 PM, Per Bothner <<a href="mailto:per.bothner@oracle.com">per.bothner@oracle.com</a>> wrote:<br>
>>><br>
>>> > The biggest annoyance I found is lack of class-level comments.  For example<br>
>>> > what is an Interpreter?  How many instances are there in the system?<br>
>>> > (I.e. is it a singleton class?  Is there one per window? One per thread?)<br>
>>> > What is the relationship to JSGlobalData, JSGlobalObject, RootObject.<br>
>>> > There are a lot of these classes, and it takes quite a bit of staring at<br>
>>> > the code to figure it out. Worse, it's hard to remember it all, so if I<br>
>>> > come back to the codebase after working on something else I have to<br>
>>> > figure out all out again: I might remember some aspects (like a class<br>
>>> > starting with JS is probably some kind of JavaScript object), but not<br>
>>> > a lot of other relationships and properties of the classes.<br>
>>><br>
>>> 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.<br>

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

><br>
><br>
> I agree that self-explanatory class names are best. On the other hand, sometimes it's hard to make a name that is super clear but reasonably concise. For example, I'm not sure how I'd improve the name of JSGlobalData to make it sufficiently clear. What's really need is a "why" explanation, not a "what" explanation - why you need this special global data object. That seems like a good use for a comment. On the other hand, commenting AffineTransform with "// This object represents an affine transform in 2D space" is probably not super helpful.</p>

<p>Yes, I agree. As I said on the other thread, reviewers should make a good judgement call as to whether we should be adding a comment or not. The comment about there's one to one mapping between threads and JSGlobalData is helpful for example.</p>

<p>One big question I have is to where we should document inrer-class relationship. g.g. I've always thought we need a some comment somewhere explaining the differences between Range, Position, VisiblePosition, RenderedPosition, VisibleSelection, and FrameSelection but I don't know to where I should put it.</p>

<p>- Ryosuke<br>
</p>