Re: Design contracts and refactoring (was Re: mathn: ugly warnings)

Let me suggest an XP-style alternative; make thorough unit tests
required and make sure they "document" - and test! - the design
"contract". Some XP gurus, such as Robert Martin, have pointed out
that the test suite is an executable form of the requirements,
especially the "acceptance tests" the customer uses (or should use) to
confirm that a delivery satisfies the requirements.

One limitation of documentation is that it has no enforcement power,
so you have to write tests anyway to test conformance. The XP view is
that you should eliminate the redundancy.

My $0.02,

Dean Wampler

On 1/10/06, mathew <[e-mail]> wrote:
> 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
>
>


--
Dean Wampler
http://www.aspectprogramming.com
http://www.newaspects.com
http://www.contract4j.org