From: Dave Thomas <Dave@...>
Date: 2000-10-14T03:10:51+09:00
Subject: [ruby-talk:5519] Re: 2 ideas from Haskell

Mark Slagell <ms@iastate.edu> writes:

> There are situations where the code is not the main point of the
> document you're writing, even if it's an important part.


True, but then you're writing a document, not Ruby, and you're using
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.

> .. 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.

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.

I'd never say "eliminate all comments", because I frequently use
comments. But LP goes well beyond commenting, and I personally feel it 
goes too far.

Regards


Dave