On 2/11/2014 4:53 PM, sebb wrote:
On 11 February 2014 22:40, Thomas Neidhart <thomas.neidh...@gmail.com> 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 (jcip.net <http://jcip.net>). 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:
https://issues.apache.org/jira/browse/MATH-1098
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
www.sandglass-software.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
