Re: too many comments

On Sat, Apr 14, 2007 at 06:17:14AM +0200, [hidden email] wrote:
Andreas wrote:
> Well, I'll gladly have *that* problem :-) And I'll happily trade a few
> hundred overly lengthy comments against the 250+ uncommented classes and
> 2500+ uncommented methods in Seaside ;-)

I wouldn't. Sifting through garbage is much less fun than reading
good code. With a good design document and tutorials, I only want to see
comments on special cases/optimisations. .

> Oh, wow. Have you truly ever been in a situation where you've really
> felt that reading the comments wasn't worth it? Not on a small scale
> (I'm sure there are a few methods for which the comments are inadequate)
> but on a scale of a framework like Seaside. A situation where you'd
> rather been without any comments to begin with? I find it hard to even
> imagine what code must look like which has been "commented to death" (if
> you have an example I'd really love to check it out). Usually, that's
> not exactly the kind of problem I face ;-)

JHotDraw in a pre-sourceforge version has the javadoc style of comments.
They absolutely add nothing to the understanding of the code, while
allowing one to see half the number of relevant lines of code.

And then there's all sample code published by Apple. Every file
starts with a page full of disclaimer/copyright comments.

Stephan

_______________________________________________
Seaside mailing list
[hidden email]
http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside

Code says what the method does.
Comments (should) say what the method is*meant* to do
It is almost never the case that the two are congruent.

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Make sure your code "does nothing" gracefully.


_______________________________________________
Seaside mailing list
[hidden email]
http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside

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*.

Cheers,
   - Andreas

Stephan Eggermont wrote:
_______________________________________________
Seaside mailing list
[hidden email]
http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside

Andreas

do not worry the core seaside team is changing and improving the  
documentation of Seaside.
But now we can ***all*** help at our own level.

For once (ok this is more often in fact than that) but I really agree  
with you. We all know what is a good method
comments and smalltalk app deserve more.

Stef


_______________________________________________
Seaside mailing list
[hidden email]
http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside

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.
_______________________________________________
Seaside mailing list
[hidden email]
http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside

+1.  And one I like is explaining *why* certain decisions were made.

In the outside world, if there is some condition that is dangerous that
causes people to get hurt, someone generally puts up a sign so that
people don't get hurt over and over.  Likewise in code, if there is
something someone tried that was a lot of work which had a big
non-obvious problem down the road, throw up a sign.  If we get to the
point where we trust version information to stay around forever (or
maybe we do already), this might be a good place for that kind of
information (and in the method at least a "#see version 3 for
explanation" type reference).


tim Rowledge wrote:
_______________________________________________
Seaside mailing list
[hidden email]
http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside