[Seaside] Why seaside really sucks! COMMMMMMMENTS are MISSING
Brad Fuller
brad at sonaural.com
Thu Apr 12 19:33:47 UTC 2007
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 ;-)
More information about the Seaside
mailing list