On Tuesday 18 October 2005 11:41 am, Ara.T.Howard wrote:
> i'm confounded by this:
>    * Version 0.0.1: The initial Stack class is release.
>
>        why on earth would all digits begin numbering at zero __except__
> build? seems that it should be version 0.0.0

Ok, point taken.

>    * Version 1.1.0: push now returns the value pushed (it used it return
> nil).
>
>        why would this not be 2.0.0 - remembering we're at 1.0.0 from 'eg
> 3'? clearly code which had done
>
>          values.inject(stack){|accum, val| accum.push val or accum}
>
>        would no longer work.  

You make a good argument for 2.0.0.  Perhaps the example is flawed.  My 
feeling was that it was unlikely that a method that *always* returned nil 
would be used in a value situation, hence returning a value was relatively 
safe change to make.

In real life, many API decisions are gray areas where you need to make such 
judgement calls (as the rest of your posting points out).  However, not using 
a clear-cut example in the document is clearly a document bug.  I'll address 
it when I get a chance.

Thanks for the feedback.

-- 
-- Jim Weirich    jim / weirichhouse.org     http://onestepback.org
-----------------------------------------------------------------
"Beware of bugs in the above code; I have only proved it correct, 
not tried it." -- Donald Knuth (in a memo to Peter van Emde Boas)