Reversing message for SelfDescribing values

[GoogleCodeExporter]

describeTo methods for higher-order matchers would read better if there
were a Description.appendSelfDescribing(SelfDescribing) method.  For
example, IsCollectionContaining.describeTo currently looks like this:

    public void describeTo(Description description) {
        description.appendText("a collection containing ");
        elementMatcher.describeTo(description);
    }

With my proposal, it would look like this:

    public void describeTo(Description description) {
        description.appendText("a collection containing ");
        description.appendSelfDescribing(elementMatcher);
    }

Which I find flows much better under the fingers.  This is the Reversing
Message pattern from Beck's Smalltalk Best Practice Patterns.

Unfortunately, doing this would add a method to an interface, breaking
current implementations of the Description interface, so this is something
best left until you're ready to make a few minor breaking changes.  

(However, this leads me to wonder if a BaseDescription method, much like
BaseMatcher, would also be useful--Description seems likely to evolve more
in the future than Matcher.)

Original issue reported on code.google.com by david.s...@gmail.com on 25 May 2007 at 12:31

[GoogleCodeExporter]

Good suggestion.

I think we should add this new method and also the BaseDescription class.

At the very least we should get BaseDescription in the 1.1 release.

Original comment by joe.wal...@gmail.com on 26 May 2007 at 10:28

• Changed state: Accepted

[GoogleCodeExporter]

I'd like the method to be named appendDescriptionOf.

Original comment by nat.pr...@gmail.com on 30 May 2007 at 8:27

[GoogleCodeExporter]

I agree with Nat on the name.

As for where to put the method...

Does a BaseDescription help? 

Unless the SelfDescribing interface changes to accept BaseDescription instead of
Description nobody is going to be able to get at the new method.

Unless we introduce a downcast and a new describeTo(BaseDescription) method in
BaseMatcher...

Original comment by neild...@gmail.com on 31 May 2007 at 3:29

[GoogleCodeExporter]

I think it's fine to change the Description interface.  This is an interface 
that
Matchers call not implement, so changes to the interface won't break any third 
party
matchers.

However, we do need a BaseDescription class so that third parties can implement 
new
Description implementations.  BaseDescription should leave appendText abstract 
and
implement everything else in terms of that.  Subclasses can then implement 
appendText
and get two benefits: (1) they won't have to implement any formatting 
themselves, and
(2) they are insulated from changes to the Description interface.

Original comment by nat.pr...@gmail.com on 1 Jun 2007 at 12:04

[GoogleCodeExporter]

I've checked in an implementation.

Original comment by nat.pr...@gmail.com on 1 Jun 2007 at 12:40

• Changed state: Fixed