[jdom-interest] setText() to replace children?

[guru at stinky.com]

On Thu, Jul 12, 2001 at 08:54:28AM -0400, Steven D. Keens wrote:
> I've been part of a maintenance crew which has made me into a firm believer
> in self documenting code - which setText() is not.  This whole dicussion
> about setText() makes it non self document.  And as you know it's because it
> contains an extra content.clear().

Every "set" method contains an implicit "clear."  There's also "add"
and "insert" which do not.  That's why I objected to Brett's original
proposal (remember way back then) to make setText *not* clear all the
content.

> To make it self documenting there are a few things you can do:
> 1) Rename it to removeContentAndSetText() or something like that stating
> extactly what it does.  I prefer this one.  Did anyone offer this
> suggestion?  And getText() can be renamed to something like
> getImmediateContatenatedText().  From my experience these probably won't be
> very popular method names but they sure do make things clear.

Boo.  Let's just rename "new" to "allocateAndInitializeNewInstance"
while we're at it.

> 2) Force the user to recognize in their code that setText() has some extra
> behavior.  You can only do this with exceptions. I understand your dislike
> for exceptions, particularly unchecked ones.  I want to avoid them as much
> as possible as well.  That's why I prefer option 1.

Who exactly are we trying to protect from their own stupidity here?
Someone who never read the docs, who used a "set" method and then
expected it to be an "insert" or some other thing?  I don't see it.

> 3) Remove the method altogether.  Can't do this one because many
> people seem to like setText()'s convenience.

setText(s) is a convenience method for 
 setContent( new ArrayList().add(s) ).
That's all it's ever been.  

> As for validation, do you do any validation at all?  If you don't validate
> the data, either in a DTD or schema, then I hope you have some validation
> directly in your code.

Yes, my code is validating, because no DTD will be able to validate
all the syntax or semantics, so why bother?  My code works when it
passes my unit tests, which include error-ful input test cases.  A DTD
just gives you a false sense of security.  

(Validating against a DTD can't catch out-of-bounds data, or
improperly typed data, or strip/trim whitespace; also, for such simple
use cases as embedded XHTML, or even child-elements-in-any-order, the
DTD becomes prohibitively large.  XSchema also fails to catch a lot of
cases.  Screw it.  DTDs were invented to suit the needs of SGML
processors, in which a single application must process many different
types of documents.  But XML is not SGML.  My apps know what kind of
documents they're expecting, and deal with them intimately.)

-- 
Alex Chaffee                       mailto:alex at jguru.com
jGuru - Java News and FAQs         http://www.jguru.com/alex/
Creator of Gamelan                 http://www.gamelan.com/
Founder of Purple Technology       http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/