[webkit-dev] class comments should be encouraged
per.bothner at oracle.com
Fri Jul 6 13:51:41 PDT 2012
[For the record, in an appropriate thread. No need to respond
if you feel this has been adequately discussed in the past.
I'm happy to let the thread die.]
The biggest WebKit annoyance I have is lack of class-level comments.
For example what is an Interpreter? How many instances are there in the
(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
a lot of other relationships and properties of the classes.
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.
per.bothner at oracle.com per at bothner.com http://per.bothner.com/
More information about the webkit-dev