[webkit-dev] Class-level comments in the source code
fpizlo at apple.com
Fri Jul 6 16:14:49 PDT 2012
- 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.
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...
More information about the webkit-dev