J J wrote:
>
> This cancerous, destructive idea of "self documenting code" is a big 
> barrior to people
> new to the language, and I would be willing to bet that is the main 
> reason it isn't taking
> off faster.
+100
> I can tell you I have done various projects in various languages to 
> get a feel for it, and
> never before have I felt like I could do so much so fast, and yet not 
> been able to do
> very much at all.  Why?  Because the state of documentation right now 
> is almost
> impenetrable.  Anything I do, I feel like it is probably already there 
> in some system
> that I don't know about and have no way to find out about.
>
> The main documentation right now, as far as I can tell, seems to be 
> the mailing list.
>
> "self documenting code" as a source of documentation is simply not 
> valid.  I am pretty
> surprised that such an obvious statement has so much resistance.
>
> If source code is the documentation then the bar for becomming 
> productive in the
> language is the amount of time it takes you to absorb the entire 
> Smalltalk class heirarchy
> from the browser.  And if you download a new system, then you have to 
> read through
> every line of source code from that system.  And that isn't enough, 
> simply reading the
> code isn't enough.  You have to wrap your brain around *why* it does 
> what it does.
> Otherwise any change you do is probably not going to be helpful.
Any system that has not been documented may as well have not been 
written at all, and I said that on the seaside list years ago.

I myself looked at seaside right from the beginning and was never able 
to get my head around it. Actually it is not that difficult, but because 
of lack of documentation, I lost 2 years of possible using seaside. And 
on numerous occasions I have dropped using squeak for exactly the same 
reason. I might have spent 5 more years in the squeak camp if there were 
any documentation for morphic, but as yet I still cant get anything 
basic working to the standard that I would like.

Keith

		
___________________________________________________________ 
Try the all-new Yahoo! Mail. "The New Version is radically easier to use" – The Wall Street Journal 
http://uk.docs.yahoo.com/nowyoucan.html