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" <fpi...@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 >
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
