From: Mark Slagell <ms@...>
Date: 2000-10-15T00:10:27+09:00
Subject: [ruby-talk:5533] Re: 2 ideas from Haskell

Dave Thomas wrote:
> 
>...
> the document's conventions. For example, the Ruby FAQ is marked up
> using SGML. When I want Ruby code, I say
> 
>    blah blah blah...
> 
>    <code>
>      puts "hello world"
>    </code>
> 
>    blather blather blather...
> 
> This then gets preprocessed, and the code fragment is executed. The
> result of the execution is then formatted and displayed alongside the
> code in the viewable version.

Ok.  I wouldn't ask students to submit homework in that form, but the
'lruby' prog that Michel posted more or less takes care of what I'd
originally asked about.  Always nice to be reminded how flexible ruby
is.  I can do what I want without screwing up the language for you. :-)
 
> > .. 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.
> 
> My experience is similar to yours in a way. Except... I've been more
> bitten by out of date or irrelevant comments.

Good point.  While the cure seems not so bad as the disease in my
experience, my experience is mostly pedagogical, trying to help
beginners debug their undocumented and unintentionally obsfucated C++
code.  (step 1: just what is this supposed to do? etc.)
 
> Why duplicate the information, when you can pretty much guarantee that
> at some point it will get out of date. Instead, let's work to make the
> code more readable.

Would you at least agree that there are some good exceptions beyond the
"architectural level decisions" you mentioned?  Surely regular
expressions, except in the very simplest cases, deserve short
natural-language summaries.

Thanks for articulating this by the way.  I've not heard anyone argue
your position before and so hadn't really been aware there was another
position.  So a relative lack of comments doesn't necessarily indicate
somebody being undisciplined, inconsiderate, or worst of all, living by
the "if it was hard to write, it should be hard to read" rule?  Ya learn
something new every day. :-)

  Mark