From: mathew <meta@...>
Date: 2006-01-11T04:37:33+09:00
Subject: Design contracts and refactoring (was Re: mathn: ugly warnings)

Daniel Berger wrote:

> I agree.  It looks like mathn, rational, complex and matrix could all 
> use some cleanup.  Unfortunately, without any unit tests (that I could 
> find, either in the ruby distro or rubicon), I'm afraid to touch 
> anything.


Actually, it's worse than that. There's no documentation of what 
functionality is intentionally supported, which precludes effective 
refactoring.

I know this is going to be controversial, but I'd like to float the idea 
that nothing new should be accepted into the standard library unless its 
API is documented. Otherwise Ruby will just accrete more and more of 
these libraries that are undoubtedly useful, but nobody can touch to 
improve--'csv' being an example. And we'll have more problems like the 
change to the standard library that broke Rake.

The documentation for a library is the design contract between the 
person writing the code and the people using it. At a minimum it should 
lay out what behavior is supported, and what is mere accident. Without 
that knowledge, you basically can't refactor, and any change you make 
that breaks applications generates a lot of unnecessarily heated 
discussion along the lines of "but it worked in 1.8.3!"

The recent discussion of Mail#to_s is another example of the problem. 
The current behavior was clearly sub-optimal, but nobody knew what the 
supported behavior was supposed to be, so discussion of improving it got 
nowhere.

Then there was the change to behavior of rb_respond_to. People had 
started to rely on 'accidental' behavior, because there's this culture 
in Ruby of not documenting whether something is publically supported or not.


mathew