[Seaside] Re: too many comments

[Jason Johnson]

Andreas Raab wrote:
> Well, I'm glad Seaside is to your liking then. No pesky comments 
> getting into your way. Oh, and I'm glad you have these great design 
> documents and tutorials, too.
>
> Sorry, but this is getting ridiculous and I'm outta here. Seaside is 
> one of the worst documented frameworks I've ever seen (and given that 
> I'm used to Squeak that's saying something). And people actively 
> defending that state of affairs ... shudder. Just *shudder*.
I think you are taking this wrong.  At least you're taking me 100% 
wrong.  I wasn't defending the state of Seaside, I was only talking 
about commenting in general.  No, Seaside is not documented in a way to 
get things done in it fast.  I have been using it since last August or 
so and anytime I want to do something new I spend maybe up to an hour 
digging to figure it out, or in the worst case sending a mail to the 
list.  Of course that needs to (and according to Step, will) change.

I just saw a lot of folks building up on the one side and thought I 
would mention that this needs a balance.  Perhaps it has to do with the 
code we have had to support.  You asked if I have ever seen too many 
comments.  In Smalltalk?  No, not yet.  In C/C++/Java/etc.?  Yes, every 
time I have to modify someone's code at work.  In the worst case, one 
individual has huge preambles for every. single. function.  And what's 
worse, this person uses global variables all over the place for (his) 
convenience, but the comments make no mention of dependencies or 
anything so you can never just go in and fix one function ever.  So I 
would call that too many comments: they aren't helping me determine how 
to make changes, but they are literally 70% of each source file.

So once again; Documenting the architecture with class comments, what a 
method is supposed to do (as Tim mentioned) and similar coupled with 
well named functions, well catagorized etc. = good.
Writing enormous preambles complete with ASCII art, author of the 
method, change history to the method (all things that can easily be 
gotten elsewhere), cryptic or downright misleading method names, that 
don't even clearly explain what is supposed to happen or anything about 
assumptions made = bad.