Why NavigableSet JavaDoc states about implementation details?

Question

Why is NavigableSet JavaDoc stating about performance metrics if it's only an Interface?

If, in theory, the interface doesn't know details about its implementations, how can the NavigableSet interface describe:

"The performance of ascending operations and views is likely to be faster than that of descending ones."

There is a similar post here but a ConcurrentSkipListSet is an implementing class.

Answer 1

There's no "real" way to enforce such behavior in Java, so the documentation is used to describe the expected behavior of the interface from a performance perspective.

This is important for two aspects.

First, as a user of this interface (or any class that implements it), you should be aware of this performance consideration, and write your code accordingly. E.g., in the paragrpah you quoted, it's noted that "The performance of ascending operations and views is likely to be faster than that of descending ones". This means that if you want to iterate over a NavigableSet, you should probably iterate from start to end and not the other way round (even though both will work!).

Second, as an implementor of this interface, you should be aware that this is the expectation, and that users of the interface have probably written their code to take this behavior in to consideration (as explained in the previous paragraph). This means, e.g., that you could implement a NavigatableSet where the performance of a descending operation is better that the performance of its ascending counterpart, but you probably shouldn't - this just isn't how users will expect this class to work.