> : About what the code should do and how it does it:
> :   * the code shows "HOW", the comment shows "WHAT"
> : or, if you can:
> :   * the code shows "WHAT" so you don't need a comment telling "WHAT".
> : a supplementary comment, "WHY", might be desirable. This is usually left

> I mostly agree with those three ways of reading code.

It's not 3 ways of reading code, it's 3 things a programmer can write
about.

> I have some Python, and would like to ask for one of its best features: docstrings. 
> I don't know where the idea comes from; it is available in Matlab/Octave,
> in some flavours of lisp, and where else?

Well, I don't know what you are referring to. Is that comments that are
considered to be bound to a particular definition/declaration? if so,
SmallTalk has some of them, and Self has even more of them.

> There is one thing that is extremely useful: the function signature. Most of the WHAT
> is there, or IMHO should be.

Well, the name of the function, the names of the parameters, and that's
all. In Ruby you don't specify types. If by signature you mean the
function type, there are no signatures in Ruby.

> Now, if we had the WHAT/WHY part available for interactive ruby... 

the WHY part is really for the programmer. Ruby needs not to know why. :-)
About Interactive Ruby... what is it? I can see a lot of code in irb/ but
I don't know what it's supposed to do except a read/eval/print loop.

Mathieu Bouchard