> Self-documenting code is an ideal promoted by just about > every advocate of a given programming language or development > methodology.  Theoretically, if a procedure, or data > structure, or class is small enough to be defined on one > page, and functionally "hangs together", it is easily > understood, and by definition is the most definitive > description of its behavior.  In practice, however, separate > descriptive documents, including relevant diagrams, > cross-references, etc. is necessary in the "real world" where > engineering team membership changes constantly, and people > with different learning styles need to
> comprehend eachothers work quickly.

But in practice, most programmers in Pascal, C and Java don't write many small routines -- they write complex big ones (in part, I think, because the fixed cost in Syntax, variable definitions and managing the codefile is so great).  Browser writing tends to encourage precisely the kind of refactoring that lends to self-documentation, leading to many smaller pieces of code, and making it painful to write monolithic hunks of code (at least after you finish the "initial hack").

Also, from my reading of the literature, this might not just be a question of style: it might arguable be a question of best practices.

> Perhaps the Smalltalk engineering style as it is today has > evolved because of the exceptional cohesiveness of the > Smalltalk community.  The folks at Disney have been working > together on this project for so long that they can probably > communicate telepathically!  

I used to think this way also.  But I can say this now with high confidence.  Either their code really is strongly self-documenting, or these guys are so good, and have been working on it for so long with each other that they can communicate telepathically with ME!  Being a somewhat older guy and not very in tune with New Age stuff, I suggest that part of the problem is accepting that there *ARE* different paradigms at work here.  A recent dispute in this listserv over whether Smalltalk is just the same old stuff in an old box made this clear to me -- fighting the possibility that a different way exists for writing code -- one which seems exactly contrary to our fundamental training (that comments are documentation, and nothing else is resposible engineering) -- is a sure way never to see things differently.

I am *NOT* arguing that Smalltalk is any panacea, just that hacking Smalltalk *is* different from hacking C, Java and other OODLs.  I am not sure we are doing anyone a service by suggesting how to code Smalltalk like C or Java.

> But if the community wants to > grow, and convince an investor to put money into developing a > product using Smalltalk at its heart, we must make it easier > to comprehend the system quickly, and without telepathy :-) 

My point is that we do no favor to someone by blinding them to the best practices and concepts for coding in this system.

I, however, am not the person to ask about this -- relative, probably even to you, I am a Smalltalk newbie.  Guys like Squeak Central, Professor Johnson and the like are the ones upon whom I would rely.
 *snip*

> All I know is that it took me about 15 years, or half > my programming career, and a lot less time to be comfortable > with C and cousins.  In all fairness, I don't think I'll ever > figure out C++, and I strongly believe that many programmers > who did are probably faking it.

I understood the full implications of C++ syntax, but never "got" OOP.  Indeed, C++ exists almost to discourage using it for OOP, providing so many means to optimize around the OOP features as to make use of them arguably a bad (performance-wise) practice.  This is why so little C++ code is reusable.
 > We have probably all had the learning experience of finding > and fixing a bug such as the printOn: one you found.  I know > it was a breakthrough when it happened to me (although I have > forgotten the details - a prerogative of the aged).  Is there > a way we can turn experiences like this into a way of teaching others?

I think so (you mean printOut, I'm sure).  But I don't think it has anything to do with changing programming paradigms in Smalltalk.  I think it begins by EXPLAINING what you are looking at, and trying to soften the differences.  Hitting you over the head with some of the absolute magic of squeak, and some of the new types of code and coding and what they can do -- and motivating how to start getting those results as a matter of course.

It also means telling folks early on that they are about to see things done very differently, in a way that will appear simplistic and even at time naive and contradictory to the "sophisticated" engineering we use today; but that in fact they are simply being shown a different way to code.

This is WHY, I think, Smalltalk programming is faster.  If you code Smalltalk like C++, you will only end up with a very slow version of the code you could have written in C++.

But these questions you raise are questions of pedagogy, not questions of documentation or programming practice, and I haven't been around long enough.  You need to ask the guys who have taught this stuff --Johnson, Guzdial and others-- how it should be taught.

And don't get me wrong, I am not arguing we don't need documentation -- I'm just arguing that writing comments around self documenting code is missing the point, and can actually be dangerously obfuscatory.  There is nothing worse, in my view than seeing beginners write:

	/* Add 1 to C */
		c = c + 1;

and the like, or worse, in a piece of straight-line top-level code requiring no optimization:

	/* Divide C by 2 */
		c << 1;