commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thomas Neidhart <>
Subject Re: [math] Annotations
Date Tue, 11 Feb 2014 07:37:10 GMT
On 02/11/2014 12:01 AM, Phil Steitz wrote:
> On 2/10/14, 1:16 AM, Thomas Neidhart wrote:
>> Hi,
>> this is an issue I was thinking about for some time now, and it is quite
>> some recurrent theme that we face in Commons.
>> Considering our release practice, it is actually quite hard to come up with
>> new features as the API is more or less fixed once it has been included.
>> Ideally, this could or should be handled with alpha/beta releases were we
>> gather feedback on a new API, but due to limited resources this does not
>> seem feasible. From experience in Math we also see that when we want to
>> extend an existing API for further uses, it is sometimes impossible to be
>> backwards compatible simply because the original API did not foresee such
>> things, which is quite normal I guess.
>> Thus, I would like to discuss another approach. Add certain annotations to
>> the code that clearly mark the mark the current state of a class/type and
>> which allows us to break compatibility for such classes even in minor
>> releases.
>> As a first step I would foresee the following annotations:
>>  * Internal: Only for internal use, no guarantee about BC or may even be
>> removed without warning
>>  * Beta: New API, may be changed in minor releases after gathering feedback
>> from the community
>> Additionally, I would like to introduce also the annotations from the jcip (
>> I do not know if we can add them as dependency, but we could
>> also add them ourselves. IMO this would be of great benefit to our users if
>> it is clear if a certain class is Immutable, ThreadSafe or Not and one does
>> not have to analyze the source code to assert him/herself.
>> I created a ticket for this, and started with two annotations so far:
>> So what do you think about that?
> I agree with the problem statement; but I am not sure annotations
> are the best or only solution.  I agree with Chris that explicit
> class / method or package javadoc is a good way to communicate what
> we need to say and it has the advantage of being plain English, full
> sentences not demanding that one learn a special vocabulary or
> figure out how detached definitions apply in the context of the API.

Maybe I was not clear about that, but my intention was not to replace
javadoc with annotations, but rather add them. One can always write
additional javadoc to give more information about a specific topic.

> IIRC, we have talked before about handling the biggest problem -
> "Internal" by just doing it explicitly - i.e., o.a.c.m.internal. 
> That is not as ridiculous as it sounds.  The only reason we *need*
> to expose internal stuff is so it can be used outside the package
> where it is defined.  Therefore, .internal adds no import bloat.  It
> is also obvious and simple.
> Regarding "beta" - it seems that annotation at the class / method
> level for this might end in a maintenance morass and if / when we
> ever did build integration, all kinds of funny corner cases / breaks
> might emerger.  And for what gain, exactly, beyond just noting in
> the javadoc and release notes that something is beta and subject to
> change.  Just slapping an annotation on a class or method does not
> absolve us of the responsibility to explain why an API is unstable /
> where it is going.

Right, but at least it would allow us to tackle the problem from a
different angle than "sorry we made a mistake here, in 3 years when we
release the next major version we can fix this".

> The other stuff - threadsafety, immutability, etc, seem to me to be
> asking for maintenance pain and also harder than you might think to
> precisely define and consistently get right.  Better, IMHO to
> explicitly cover this stuff, when relevant, in plain English javadoc
> in the context of the API.

It is not mandatory, and can be added step-by-step. We did something
like this for codec, where we have written these statements (ThreadSafe
or not) in the class javadoc, which is a good thing.

> All that said, could be I am just being old-fashioned here and
> annotations will make the world much easier for us and users, so if
> others agree this is the way to go, I will try my best to help.  I
> definitely want to help attack the "internal" and "beta" problems
> somehow, so thanks, Thomas, for bringing this to the fore.

Maybe I made a mistake by mixing up two things:

 * changes to our release policy with Internal and Beta stuff
 * explicit statement of certain properties of classes like ThreadSafe

For the first point, I really think we need a better solution to what we
have today, but this could also be a different solution.

The second one would be mainly for convenience imo.


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message