[Seaside] Why seaside really sucks! COMMMMMMMENTS are MISSING

[Brad Fuller]

Jason Johnson wrote:
> I'm surprised to be saying this, but one must not forget that 
> commenting also has a cost.

Absolutely, it's a pain to do, costs LOTS of time and agony. But, the 
rewards for others down the line are greater if done well.

Pay it forward.

> My current rule is that a comment shouldn't say what something does.  
> If the code is so unclear that it would need such a comment it should 
> be rewritten

The value of comments, for me, is in the architecture description, the 
concepts of the code and how to use it efficiently - more from a macro 
view than a micro view. That's what I would like to see more of. I don't 
necessarily care if the author explains what he does at the method level 
unless it's crucial to understanding the usage and concepts of the 
application. I want to understand from the author the architectural 
design, the plumbing and how to use what he gave us.  From this 
perspective, I think it would make it easier for authors to comment. 
They don't have to comment every little method, and they get to show off 
their pride and joy by describing (in detail!) their baby.


> (obviously if you're doing optimized code this rule has to be relaxed 
> a bit).  Comments should say what the code doesn't (e.g. why was it 
> done this way?  Are there some non-obvious dependencies here?) [1].
>
> And what is with the first person commenting?  For me it doesn't add 
> anything but typing/reading, with no value add.
>
> "I am the method responsible for rendering the class..."
>
> vs.
>
> "responsible for rendering the class..."
+1. Except if the code actually wrote the comment itself ;-)