Alex is a Software Engineer working on Android development tools, especially Android Studio, at Google. His interests include Java, API design, OOP, IDEs and testing. Alex spends some of his spare time working on Open Source, blogging, writing technical articles, and speaking at international conferences. The opinions expressed here represent his own and not those of his employer. Alex is a DZone MVB and is not an employee of DZone and has posted 49 posts at DZone. You can read more from them at their website. View Full User Profile

Fluent Interfaces: Don't Chain for the Sake of Chaining

09.18.2012
| 5021 views |
  • submit to reddit

One of the goals of FEST-Assert 2.0 is to learn from the mistakes we made in the 1.x releases, even if that means not being backwards-compatible.

Not fully understanding the semantics of the API we were building, is, IMHO, one of the biggest mistakes we made in FEST 1.x. We were not able to see that each assertion in the method chain should be an independent unit.

To better explain my point of view, consider this snippet using FEST-Reflect‘s API:

Person person = constructor().withParameterTypes(String.class)
                             .in(Person.class)
                             .newInstance("Yoda");

In this example, each chained method in the fluent interface serve a common purpose: instantiate a new Person (similar to the builder pattern.)

On the other hand, in FEST-Assert, each method in the fluent interface has its own, individual purpose. For example:

assertThat(yoda).isInstanceOf(Jedi.class)
                .isEqualTo(foundJedi)
                .isNotEqualTo(foundSith);

The purpose of isInstanceOf is different than the one from isNotEqualTo. We can even call them individually:

assertThat(yoda).isInstanceOf(Jedi.class);
assertThat(yoda).isEqualTo(foundJedi);
assertThat(yoda).isNotEqualTo(foundSith);

In FEST 1.x I broke this assumption by introducing overridingErrorMessage as a way to override FEST’s default error message in case an assertion fails. Let’s take a look at this example:

assertThat(yoda).overridingErrorMessage("Yoda is a Jedi, dammit!")
                .isInstanceOf(Jedi.class)
                .isEqualTo(foundJedi)
                .isNotEqualTo(foundSith);

This is when it gets confusing. Now a method in the chain affects the behavior of the next one. It is hard to tell if overridingErrorMessage only applies to isInstanceOf, or to all the methods in the chain. It is so confusing that I cannot remember what were the semantics of overridingErrorMessage!

This is a potential fix:

assertThat(yoda).isInstanceOf(Jedi.class, overridingErrorMessage("Yoda is a Jedi, dammit!"))
                .isEqualTo(foundJedi)
                .isNotEqualTo(foundSith);

Now it is easier to understand that overridingErrorMessage only affects isInstanceOf.

Looking back, I can see that I introduced overridingErrorMessage the way I did because I naively thought that method chaining makes it easier to write and read code. It surely makes it easier to write code (just press “.” and your IDE’s content assist will show you all the available methods) but I showed you that chaining methods does not always produce a readable API.

In short: I abused method chaining.

Conclusion

When creating a fluent interface using method chaining, step back and think what are you trying to achieve. Do the methods in the chain share a common purpose? Are you chaining a bunch or independent methods? Regardless of the style you choose, be consistent and try not to mix them. That will make the code written with your API readable.

Oh BTW, we made the same mistake (again) in FEST-Assert 2.x. Luckily, there is still time to fix it :)

Published at DZone with permission of Alex Ruiz, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Tags:

Comments

David Karr replied on Wed, 2012/09/19 - 12:59pm

Good to hear. I stopped even trying to use overridingErrorMessage when I realized how odd the interface was.

Alex Ruiz replied on Wed, 2012/09/19 - 11:29pm in response to: David Karr

David, I'm glad it makes sense to you too. Out of curiosity, did you raise this issue in the FEST mailing list?  

Cheers! 

David Karr replied on Wed, 2012/09/19 - 11:43pm

Yup. https://groups.google.com/forum/?fromgroups=#!topic/easytesting/D9I83jDgcwk .

Alex Ruiz replied on Thu, 2012/09/20 - 10:50am

I'm so sorry David. That was the time I wasn't around actively working on FEST.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.