Document which classes support inheritance and which do not

[jbduncan]

Overview

Currently, AFAICT, no classes (apart from utilities classes) document their support for inheritance (that is, whether they are designed to be subclassed or not). Effective Java 2nd edition, Item 16 describes the dangers of allowing users and extension writers to subclass JUnit 5 classes that aren't designed for inheritance. Therefore we should follow Item 17's advice to prevent this.

Specifically, each class should meet the following criteria (more or less ripped from the book):

1. For classes that support inheritance:
   1. Make those methods which aren't intended to be overridden final.
   2. The class must document it's self-use of overridable methods.
   3. To allow programmers to write efficient subclasses without undue pain, a class may have to provide hooks into its internal workings in the form of judiciously chosen protected methods or fields.
   4. The only way to test a class designed for inheritance is to write subclasses; classes must be tested by writing subclasses before releasing it. (Before GA, in our case.)
   5. Constructors must not invoke overridable methods.
   6. For classes implementing Cloneable or Serializable, neither clone nor readObject may invoke an overridable method, directly or indirectly.
2. For classes that don't support inheritance:
   1. Prohibit subclassing by making the class final or replacing all public constructors with public static factory methods.

Deliverables

• Each and every class meets the criteria above.

[sbrannen]

slated for RC1 for team discussion

[stale]

This issue has been automatically marked as stale because it has not had recent activity. Given the limited bandwidth of the team, it will be automatically closed if no further activity occurs. Thank you for your contribution.

[jbduncan]

I'd still like for this to be addressed at some point.

[jbduncan]

That being said, I understand if some classes/methods can't be made final now for backward-compatibility reasons, but at the very least each and every public class and method should be documented appropriately.

[marcphilipp]

We have done so in a few places, e.g.:

junit5/junit-jupiter-params/src/main/java/org/junit/jupiter/params/aggregator/ArgumentsAccessor.java

Line 35 in 17d3b44

* <p>This interface is not intended to be implemented by clients.

junit5/junit-platform-launcher/src/main/java/org/junit/platform/launcher/TestPlan.java

Line 52 in 17d3b44

* <p>This class is not intended to be extended by clients.

@jbduncan Is this something you think you could contribute via a PR?

[jbduncan]

@marcphilipp Oh, excellent!

I've also seen that this file has some inheritance-related info:

junit5/junit-jupiter-api/src/main/java/org/junit/jupiter/api/Assertions.java

Lines 82 to 84 in 419ddb1

	* <p>Although it is technically possible to extend this class, extension is
	* strongly discouraged. The JUnit Team highly recommends that the methods
	* defined in this class be used via <em>static imports</em>.

Yes, I'd love to raise a PR, but I'm currently juggling a PR for junit-pioneer and some real life commitments, so I've put this issue on my TODO list. :)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. Given the limited bandwidth of the team, it will be automatically closed if no further activity occurs. Thank you for your contribution.

[jbduncan]

I'm still interested in contributing this eventually.