[ruby-talk:04119] Re: Method signature - a question for the group

Hi,

hipster wrote:

> On Tue, 18 Jul 2000  14:24:05 -0500, Dave Thomas wrote:
> >
> > However, String#index can return either a Fixnum or nil, depending on
> > whether the substring was found, so in this particular case we
> > document it as
> >
> >       str.index( aString ) -> aFixnum or nil
> >
> > We also describe in the text that follows the circumstances under
> > which nil is returned.
> >
> > The problem is that these "or nil"s appear all over the place (and
> > we're discovered places where they're missing), and they mess up the
> > layout of the method definitions somewhat. So, we were wondering: do
> > people feel they're useful to include in the signature, or is noting
> > them in the accompanying text good enough?
>
> I think including this info in the signature is useful. Often when I'm
> doing a quick vgrep for a method, I only read its signature.
>
> Maybe
>         str.index( aString ) -> aFixnum | nil

As a user/reader, I certainly strongly prefer something like this to
omitting nil.

However, I'm much less certain whether this preference would be widely
shared. But even if it were not, there is another factor that might come
into play. Half the time when I look stuff up, I don't read the text, so
having to read through the text every time to search for possibly missing
information would soon become annoying. I suspect this would be true for
some significant fraction of other readers, regardless of their initial
preferences.

However, the bottom line is that I would still buy/recommend the book and
subsequent editions in any case.

JM2CWONOHO

(Just my 2 cents worth of not overly humble opinion. :-)

--
Conrad Schneiker
(This note is unofficial and subject to improvement without notice.)