Mathieu Bouchard <matju / cam.org> wrote:

: 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
: out, but in many circumstances it would be helpful, if only to prevent a
: random programmer from rewriting your code while thinking you are an
: idiot. 

Hi,

I mostly agree with those three ways of reading code. 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? 

The HOW should be obvious from code, except for tricks and delicate things
which I tend to comment. (I would fall in love with an editor that allowed
me to put diagrams into my code. I have to do that one day. ) There is one
thing that is extremely useful: the function signature. Most of the WHAT
is there, or IMHO should be.

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

lacking-superlatives-ly y'rs

DCA

-- Daniel Calvelo Aros
     calvelo / lifl.fr