jsr339-experts@jax-rs-spec.java.net

[jsr339-experts] Re: HEADS-UP: Decide on fluent client API atributes: simplicity vs. consistency

From: Bill Burke <bburke_at_redhat.com>
Date: Thu, 25 Aug 2011 16:27:17 -0400

On 8/25/11 3:33 PM, Marek Potociar wrote:
> On 08/25/2011 08:25 PM, Bill Burke wrote:
>>
>>
>> On 8/25/11 12:49 PM, Markus KARG wrote:
>>> While I understand Bill's concerns as a vendor, I need to say that I more care for preventing errors than for reducing
>>> the number of classes in this case. As the user will only get in touch the methods, but not directly get in touch with
>>> the classes (they do not care that the methods in turn create instances of different classes) the number of classes
>>> should not become a problems for users.
>>>
>>
>> This has nothing to do about being a vendor. Its about users being able to understand the API. I don't know where you
>> got that idea from...
>>
>
> I would side Markus here - understanding of a fluent API is not expected to be conveyed as a list of class and method
> descriptions. It's like learning English from a dictionary without understanding the proper sentence structure. Fluent
> API's are best learned by examples. Class hierarchy plays a marginal role when it comes to learning how to use a
> *fluent* API.
>

You make it sound like I'm against a fluent API, I'm not. I just think
you can be both fluent and readable, especially when the inconsistencies
you've outlined are both edge cases, opinion-based inconsistencies, and
something the user will never run into. I've also pointed out a few
instances where your API is quite awkward to use.

In English, there's many ways to structure a sentence to say the same
thing. For example:

Your API is like spaghetti to me.
Your API, to me, is like spaghetti.
Your API is, to me, like spaghetti.
To me, your API is like spaghetti.

Its all a matter of perspective. Same could be said for how one would
like to build an HTTP request. But, saying that "understanding a fluent
API is not expected to be conveyed as a list of...descriptions" is a
huge cop-out, a lame excuse for a bad design. Especially when we're
arguing about trivial differences in opinion that nobody really cares
about outside of this list!

Anyways, good luck, it's clear I'm not getting anywhere with these
arguments, so I give up.

-- 
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com