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

[Ryosuke Niwa]

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/f54b8336/attachment.html>