[jdom-interest] TODO subclassing [eg]

[Joseph Bowbeer]

Dennis Sosnoski writes:

> I'd suggest that rather than saying "never" it should be a
> requirement that overridable methods used in constructors
> (or clone, or readObject) be documented as such so that
> anyone considering overriding them is aware of the potential
> pitfalls.

OK.  These are just rules and experts know when to break the rules.

How about striving for "never" and documenting the constructor's
implementation when we can't abide?


----- Original Message -----
From: "Dennis Sosnoski" <dms at sosnoski.com>
To: "Joseph Bowbeer" <jozart at csi.com>
Cc: <jdom-interest at jdom.org>
Sent: Saturday, April 14, 2001 11:27 AM
Subject: Re: [jdom-interest] TODO subclassing [eg]

I'd suggest that rather than saying "never" it should be a requirement that
overridable methods used in constructors (or clone, or readObject) be
documented as such so that anyone considering overriding them is aware of
the potential pitfalls. There may be cases where you really want the
subclass to be able to change the way the superclass is initialized, for
instance.

Personally, I try to avoid structuring my code so that overriding of
non-abstract methods is required at all. It's often difficult to avoid with
libraries, though.

  - Dennis

Joseph Bowbeer wrote:

> Tweaking JDOM for subclassing is a TODO topic in itself.
>
> 1. There are some specific things we can avoid, such as never calling
> overridable methods from constructors and "pseudo-constructors" (clone and
> readObject).  Note: "overridable" means not final and either protected or
> public.
>
> Rationale [quoted from Effective Java by Josh Bloch]:
>
> Constructor: "The superclass constructor runs before the subclass
> constructor, so the overriding method in the subclass will get invoked
> before the subclass constructor has run."
>
> clone: "If clone invokes an overridden method, this method will execute
> before the subclass in which it is defined has had a chance to fix its
> state in the clone ..."
>
> readObject: "... the overriding method will run before the subclass's
> state has been deserialized."
>
> 2. There are also some design/documentation issues concerning what
> subclasses are allowed to do.
>
> Here's what Effective Java advises:
>
> "The class must document precisely the effects of overriding any method.
> [...]  In other words, the class must document its self-use of overridable
> methods: for each public or protected method, the documentation must
> indicate which overridable methods are invoked by that method, in what
> sequence they are invoked, and how the results of each invocation affect
> subsequent processing. By convention, this description is placed at the
> end of the javadoc comment for each method, and begins with the phrase
> _This implementation_."
>
> The java.util.AbstractCollection javadoc is good a example.
>
> --
> Joe Bowbeer
>