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

Mathieu Bouchard <[e-mail]> wrote:

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

Of course. Fast fingers and slow brains: me.

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

In Python, a string placed right after a function or class declaration is 
put by the compiler into a variable called function.__doc__ ; it is 
afterwards available to the outside world.

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

I meant irb, the program. What I meant more precisely was that docstrings
allow you to have (part of) the documentation of your modules available,
at the same level as .methods et al.

Sorry to introduce Python, but I'm not yet comfortable enough with Ruby.
You have this feature Python. If you declare in file aModule.py:

# aModule.py
def aFunc(anArg):
  " A string right after the declaration. It is a 'docstring'."
  print "hi"

Then, in the interactive Python interpreter:
>>> import aModule
>>> print aModule.aFunc.__doc__
 A string right after the declaration. It is a 'docstring'.

Because I tend to test my programs with the interactive interpreter, I use
this feature to look for usage messages, usage warnings and the like.
Most of the standard libray has docstring documentation. The WHAT part 
I mentioned above is what may go into docstrings, along with some WHY.

As for signatures, of course Ruby is not typed. But routines may require
their arguments to respond to specific messages; it is IMHO useful to
state some set of requirements on the arguments of a function. This is
docstring-land.

: Mathieu Bouchard

bear-with-my-limping-english-ly yours, Daniel.

-- Daniel Calvelo Aros
     [e-mail]