[Seaside] Re: too many comments
jbjohns at libsource.com
Sun Apr 15 08:20:16 UTC 2007
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.
More information about the Seaside