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

[Filip Pizlo]

At least for JavaScriptCore, I think that this is not a solvable problem.  I suspect there are other parts of the code where this is true.  There are many central classes that have such subtle behavior, which changes so often, that:

- If you had a comment then it would be perpetually inaccurate.

- If you tried to show change log entries for that class, you would be overwhelmed.

I think if you want to understand many of the hairy parts of the code, you just need to read it.

-F



On Jul 6, 2012, at 4:11 PM, Ryosuke Niwa wrote:

> 
> On Jul 6, 2012 3:04 PM, "Filip Pizlo" <fpizlo at apple.com> wrote:
> >
> > It is indeed a problem of incentives.
> >
> > Nobody has the incentive to maintain a class comment when making changes, since comments are not checked by the compiler.
> >
> > Therefore, it's much better to not write comments, and instead find other ways of making the code legible.
> 
> I think explaning the relationship between classes for ones that are not self-explanatory will be helpful and will probably incur very little cost compared to comments in functions.
> 
> But I do agree that keeping them up-to-date is very challenging. This is why I usually prefer keeping such comments in a change log entry since a change log entry explains the state of things at one partiuclar revision, not for an indefinite time into the future.
> 
> Perhaps we need some tool that shows relevant change log entries for each line in the code.
> 
> - Ryosuke
> 

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