[ruby-talk:03680] Re: Ruby coding standard?

From: "Mathieu Bouchard" <[e-mail]>


> > : 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?

Eiffel has this feature too, where after the method-signature should be a
comment, describing what the
method does. Additionally, Eiffel has the "indexing"-keyword, where you can
give a class some describing attrributes, like title, date of creation and
author. Both can be used to automatically create documentation.

--
Michael