Effective Java! Design and Document Classes for Inheritance or Else Prohibit It.

In our review of the last chapter we talked about the dangers of implementation inheritance. The point was conceded that sometimes implementation inheritance is the correct thing to do. It is these cases that we are going to talk about today. How to help implementation inheritance succeed.

The first thing to know is that you should document the effects of overriding each overridable methods(i.e. methods that are non-final and public or protected). This means that you must document when the class uses it’s own methods internally and thus where overriding a method can have unexpected results. We saw an example of this in a previous chapter’s review. Other things that should be documented are whether this method could be called from a static context, from a background thread, etc. Anything that could affect how an implementer implements a method.

As of Java 8 a new capability was added to JavaDoc to facilitate this. This capability adds a new section in the documentation that is specifically to facilitate this documentation, @implspec. Let's seem an example of the use of this in java.util.AbstractCollection's remove method's JavaDoc.

{@inheritDoc}
This implementation iterates over the collection looking for the specified
element.  If it finds the element, it removes the element from the collection
using the iterator's remove method.
Note that this implementation throws an…