Re: re: TrueType font support and 3.6

Colin Putney <[email protected]> wrote:
[SNIP]
> The problem is that "clear and easy to understand" is a difficult 
> standard for the Guides to apply. But I urge them not to settle for the 
> easier standard of "has comments." Sure, the review process needs some 

I didn't have time to comment on all aspects in this thread but just so
people understand - of course I didn't mean that 100% of all methods
need comments (there are accessors,  a few #isBlabla methods and other
obviously readable methods that could go without comments)... But in
general I *want* method comments! 

On the other hand the current base classes (due to reasons we all know -
so I am not placing any blame whatsoever) are definitely less commented
than they should be. And in order to make this *better* we actually need
to make sure that stuff going in *should be properly commented*, right?
And of course this is a "review thing" - people will disagree sometimes.

But I stand firm behind what I said - *Personally I will not let
uncommented code into the base image*. This doesn't imply that 100% of
the methods need robotlike comments - but it means that the code should
be commented enough to satisfy *me*. :-) That is after all what
reviewing is all about.

Now, people can of course argue that Beck is right - if there is a need
for comments, write better code. And to some extent I agree (Kent is my
favourite Smalltalk hero after all) - at least as a driving mechanism to
make people refactor code instead of trying to explain what the
spaghetti does. I don't view it as a goal to not have comments though.

And fine - if the code is *that* clean cut and easy to understand - then
perhaps a few methods may slip by. I typically react when I read code
that I don't understand *and* that lacks comments.

This all boils down to what people think a method comment should "do".
IMHO the method comment is the piece of information missing from only
reading the message selector and the class comment. If you have read the
class comment (so that you understand what a PluddaBudda actually *is*)
and then read the message selector #pludder, then you have some idea of
what it does. The method comment should fill in the rest you *need* to
actually know *what* it does.

So the point is that mere users of an object shouldn't be *forced* to
read the method code in order to understand (or at least have a pretty
good idea) *what* the method does. If they want to know *how* it does it
- then fine - read the damn code.

And then of course the existence of a method comment also signals to me
that the author has tried to write down what he/she thinks I need to
know. So if the comment is simple and short I can rest assured there are
no "gotchas" in this method I need to be aware of. If the comments isn't
there then I am in the dark - does it actaully lack gotchas or did the
author simply forget to write them down? Quite important aspect IMHO.

Then there are of course a bunch of "exceptions to the rule" - but that
is my view of it generally. Remember again - we are talking about *base*
classes.

regards, Göran

PS. Hey, that turned into a rather long reply. :-)