commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Adrian Crum <>
Subject Re: [math] Annotations
Date Wed, 12 Feb 2014 15:52:22 GMT
On 2/11/2014 4:53 PM, sebb wrote:
> On 11 February 2014 22:40, Thomas Neidhart <> wrote:
>> On 02/10/2014 10: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?
>> It looks like I am pretty much the only one that sees a value in this
>> stuff, so I guess it is better to not change anything.
> I am keen that code should be documented to say whether a class is
> supposed to be thread-safe / immutable / not thread-safe etc.
> Also to document how mutable variables are protected (@GuardedBy).
> I think this is important both for the user of the code, and
> particularly for the maintainer.
> There's no point struggling to ensure thread-safety for a class that
> is not intended to be shared across threads, equally if a class is
> supposed to be shareable it is vital to ensure updates don't break it.
> I think the best way of doing this is via annotations (plus inline
> comment if really needed).
> As an example of why I think annotations are better, compare:
> @GuardedBy("this")
> private int index;
> with
> /*
> * thread-safety of the index is guaranteed by synchronising on the
> class instance
> */
> private int index;

I use a similar approach in Apache OFBiz. The @ThreadSafe and @GuardedBy 
annotations really make it easier for me to understand how a block of 
code works - especially when I haven't touched the code in a while and 
I've forgotten those details. (Btw, I would recommend adding 
@ClassInvariant to the list.)

If the annotation interfaces include the @Documented annotation, then 
the annotation is included in JavaDocs - so they aren't much different 
than JavaDoc comments. If a developer needs any more detail, they can go 
to the interface's JavaDocs. The annotations being proposed here are 
pretty basic and intuitive, so I don't see them as being some kind of 
hurdle a developer needs to overcome.

Adrian Crum
Sandglass Software

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

View raw message