Thoughts from an outsider

Ramon Leon ramon.leon at allresnet.com
Wed Aug 30 18:35:42 UTC 2006


> The fact is, no matter how obvious the language is there are 
> patterns we use.  Sure in some instanses the method can be 
> obvious enough to be understood.  But there are plenty of OO 
> patterns that are not obvious if you have not seen them 
> before and sometimes even if you have.  You may be able to 
> read from the code what it is doing, but you are going to be 
> thinking "why in the world is he doing this?".
> 
> Also, if you work with a pretty complicated subsystem (i.e. 
> uses lots of underlying objects to get work done) do you 
> really find it a good solution to dig through class after 
> class after class just to find out what an interface (i.e. 
> what the subsystem end users use) method does?  And even if 
> you do, someone new to the language isn't.

This is the difference between using a framework and using an API,
Smalltalkers like frameworks, which by their very nature, require you to
understand how they work.  You make it sound like digging through classes is
hard, it's just a couple keystrokes, browse here, browse, there, check out a
few examples, bam, ok, makes sense now.  I not only find digging through
classes a good solution, I find it's the only one I've ever found that
works.  Documents lie, code doesn't.  I consider understanding how something
works, a prerequisite to using it well.  And frankly, I can bounce around
the code, in a far more organized and faster manner than I could through
some document.

> And must every usage of a new subsystem be a trip through 
> every method in that system?  Can't I just get a list of what 
> the useful methods are and how to use them?

If you have a task to perform, you should be able to just browser class
names to see who might do that, it's a simple task to quickly check a class
for it's responsibilities.  Well designed frameworks make this a breeze.  As
I said earlier, getting a list of the useful methods and how to use them, is
only a hotkey or two away.  

> I appreciate the simplicity of the language, but it is 
> because of this reason one must guard against the false 
> feeling of "self documenting code".  You don't have to 
> document every method ever, but ANY interface to the 
> subsystem should be documented some how and any method over a 
> certain number of lines should be documented.
> 
> Even if you coded right in pure English, I still wouldn't 
> know *why* you did it the way you did, and therefore I 
> wouldn't know *why* I shouldn't just change it.
> 

Self documenting code is not a false feeling, it's a point of view.
Smalltalkers in general don't write long methods, so that's not an issue.  I
find class and method comments, totally sufficient for me to grok how a
system works, a quick look at the hierarchy browser, couple of samples of
those classes in use, and away I go.  I usually find when something is done
weird, there is a comment explaining why it was done that way right there in
the code, as it should be.  

I appreciate that some people want more documentation, that's a valid point
of view, but let's not insist that those of us who think the many browsers,
classes, categories, method categories, and class and method comments are
sufficient documentation are somehow foolish, we're not.  Some people need
instructions on how to assemble things, others just look at the parts,
tinker a bit, and figure it out, Smalltalk is wonderful for those in the
latter camp.  I'll take being able to look directly at the class over
looking at a document any day of the week, it's the best documentation there
is as far as I'm concerned.




More information about the Squeak-dev mailing list