[jdom-interest] Fast Factory

[Dennis Sosnoski]

Elliotte Rusty Harold wrote:

> At 10:36 AM -0700 5/23/03, Dennis Sosnoski wrote:
>
>> I have a hard time understanding the emotional weight this issue 
>> apparently carries for you. I'm not suggesting removing verification 
>> from JDOM, but only making it optional where practical. That would 
>> give developers the freedom to turn it off if they want, at the risk 
>> of shooting themselves in the foot. That's a tradeoff that most APIs 
>> provide and that Java developers generally seem to like.
>
>
> The whole point of an API is to keep developers from shooting 
> themselves in the foot. A developer uses an API because the API 
> designer knows more about the problem domain than the client 
> programmer does.

There's often some degree of specialized knowledge embedded in an API, 
but I'd argue that the primary purpose of an API is normally 
convenience. An API should provide a simple and easy way of working in 
the problem domain, without substantial performance penalties. If it 
doesn't, developers will either bypass the API or use an alternative API.

> I'm glad the java.net APIs remove from me the responsibility of 
> knowing every last detail of IP packet formats. I can rely on the API 
> to do the work for me. Similarly in XML we must not assume the client 
> programmers know as much as we do.

Nor should you assume that the client programmers are idiots who don't 
know what they're doing. If you *do* make this assumption, you'll end up 
with an API that's only used by idiots who don't know what they're doing.

> They are looking to JDOM precisely so they don't have to know every 
> last detail of XML like which C0 characters they can and cannot use in 
> text nodes. 

This is certainly one plausible goal for writing an XML API, that it 
allow only constructing well-formed XML documents. I assume it's a major 
goal of your XOM project. It's *not* one of the stated goals for the 
JDOM project, AFAIKS.

> I have noticed that Java developers as a group tend to be relatively 
> uneducated about preconditions, postconditions, and class invariants 
> as opposed to, say, Eiffel or even C++ programmers. This probably has 
> to do with Java's lack of language level support for such features, a 
> lack of support that continues with  the incredibly broken assertions 
> mechanism introduced in Java 1.4. However, the fact remains that class 
> invariants are at the core of data encapsulation, and are a critical 
> aspect of object oriented programming. Turning off class invariants is 
> at the same level as exposing fields as public, directly accessible 
> data. (Indeed the two practices go hand in hand.) Now maybe you don't 
> want to write object oriented programs, and that's OK; but if we are 
> going to design an object oriented API for an object oriented 
> language, then class invariants shouldn't be an issue, any more than 
> private fields. 

The key choice in this is always how you choose the preconditions, 
postconditions, and class invariants. You're advocating that every 
character of data be verified, making verified data part of the class 
invariants - except for data coming from something that looks like a 
parser, which means it's *not* really a class invariant anymore. I'm 
suggesting there may be other cases where people also want to turn off 
the character verification in the interest of performance, and I think 
they should be able to do so.

Beyond that, I clearly favor APIs that provide flexibility while you 
favor APIs that enforce structure. This is a philosophical issue that 
I'd love to discuss with you over beer sometime, but not something that 
can ever be resolved on a general level.

  - Dennis