[ruby-talk:5515] Re: 2 ideas from Haskell

Dave Thomas wrote:
> 
> Mark Slagell <[e-mail]> writes:
> 
> > 1. a "literate mode" that assumes all lines in a script are comments
> > unless the first column is a special character (Haskell uses '>').
> 
> This is an interesting concept. It's interesting because it assumes
> that the source code is not readily understood, and that therefore
> I'll be needing to write more comments that source to explain myself
> (otherwise why make the source code harder to type than comments?)
> 
> That might be true for some languages (APL springs to mind). It might
> be true for Haskell (although in general it seems pretty
> readable). But I don't think it is true of Ruby.
> 
> Ruby programs read pretty well--there's not much about them that's too
> obscure, and with well chosen method and class names, a Ruby program
> pretty much documents itself. Comments can be reserved for documenting
> architectural level decisions.
> 
> So I'm not sure that adding this kind of facility helps much. Could
> someone convince me?
> 
> Thanks
> 
> Dave

I'm not basing any of this on an assumption that all or even most source
code is not readily understood, nor arguing that all or most code should
be relegated to this comments-supreme mode.  The innate readability of
ruby, for what it's worth, isn't entirely what I'm concerned with here.  

There are situations where the code is not the main point of the
document you're writing, even if it's an important part.  Some kinds of
conceivable documentation would benefit from this (read a web page
containing some instructional text, then test the code it contains by
dumping the html page directly into the interpreter instead of
downloading a separate script or copy/pasting, why not?).  For another
example, to be able to use ruby in a college programming course, it
would be ideal to be able to intersperse runnable code with answers to
homework exercises.  And I do think ruby is going to be the _ideal_
instructional language for beginners if the academic world notices it.

 -- Mark


... and this almost belongs off to the side, but I do want to respond to
your self-documentation observation. I agree in principle but am alarmed
when clear coding practices are so trusted, to the entire exclusion of
comments.  I can at least speak from personal experience - I consider
myself a reasonably bright guy, a decent programmer but not a language
scholar; and I know I have a pretty high 'huh?' factor when reading
almost anybody else's code, even when it is ruby code.  There seems very
often in the programming languages community to be a pervasive lack of
comprehension of how people who are not language scholars think. 
Self-documenting code is good.  Self-documenting code with explanations
added is much, much better.  A sop to the masses.