On 11 February 2014 22:40, Thomas Neidhart <[email protected]> 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;
> Thomas
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [email protected]
> For additional commands, e-mail: [email protected]
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
