From: "NAKAMURA, Hiroshi" <nahi@...>
Date: 2004-02-13T15:14:49+09:00
Subject: Re: Standard libraries

Hi,

> From: "Gavin Sinclair" <gsinclair@soyabean.com.au>
> Sent: Friday, February 13, 2004 2:54 PM

> >> Method documentation is neccesary to help people understand the code -
> >> I agree.
> >
> > I hope you allow me, I don't agree.
> 
> Of course I allow you :)  I'm curious what your reasons are.

Thanks.

From my experience, for good development, library user
should read the source instead of per method document
(and library developer should aware of it).

# I don't mean all documents are wrong.  Concept, design,
# performance analysis could not be written in the source.

> This is how I would comment it.
> 
>   class Row < Array
>     #
>     # Returns the strings contained in the row's cells.
>     #
>     def to_a
>       self.collect { |cell| cell.is_null ? nil : cell.data }
>     end
>   end
> 
> Notice I avoid duplication.  You say "Returns an Array of String".  But
> to_a *obviously* returns an array.  You name the method explicitly, but
> there's no need.  You mention "Null is converted to nil", but that is
> entirely predictable behaviour.  It's not unreasonable to document that,
> though.
> 
> Notice that the single sentence I wrote as documentation is something that
> is unlikely to change.

Sure.  I'll adopt it. :-)

I start thinking that I could be live with the new culture.
Thanks.

> Don't get too carried away ;)  The proposed criteria for inclusion in the
> standard library covered *new* additions.  I don't think Matz will throw
> half the current library away before 1.8.2 :)

I hope so.  But special amnesty person (old library author)
will do nothing without deadline...(I am).

Regards,
// NaHi