Lex Spoon wrote:


> Here's a better example: class HtmlEntity, which has a subclass for each
> HTML tag.  Does HtmlImage really need to have a comment like "HtmlImage
> is for <image> entities" ?  That seems wasteful to me.  To understand
> HtmlImage you need to understand its superclass; once you understand its
> superclass, no comment is necessary.  HtmlImage is no more and no less
> than what it's name suggests: an entity for images.
> 
I'm going to disagree again here; this is ripe with possibility. One 
might include a pointer to the appropriate page on the W3C site where 
html image tags are defined, have a list of any limitations or problems 
with their use within the context of the system etc.

But let's not throw too much of our time at specifics. Clearly people 
can differ on what they think is appropriate. The good news is that more 
than is needed by one person is unlikely to be troublesome to that 
person, barring otiose prolixity and redundantly excessive verbiage, and 
it is probably helpful to others. The bad news is that carefully written 
highly explanatory commetns can be ruined by code being changed without 
the comment being updated.

tim