You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Thomas Neidhart <th...@gmail.com> on 2014/02/10 10:16:53 UTC
[math] Annotations
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). 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?
Thomas
Re: [math] Annotations
Posted by Chris <ca...@gmail.com>.
If you could get the tool support there, then I could definitely see a
reason for the annotations. Without the tool support though, it just seems
like unnecessary documentation bloat.
On Mon, Feb 10, 2014 at 2:56 PM, Thomas Neidhart
<th...@gmail.com>wrote:
> On 02/10/2014 05:44 PM, Chris wrote:
> > Hi Thomas,
> >
> > If this is only for documentary purposes, it seems a bit strange in my
> > mind. Wouldn't a comment at the header serve the same purpose?
>
> right now it would mainly be used for documentation purposes as tool
> support is not yet there. Instead of browsing through the class javadoc
> a user may immediately see the corresponding annotation.
>
> For the future, I see several benefits:
>
> * integrate these annotations in our currently used build-tools, e.g.
> clirr could be instructed to ignore classes that are annotated as
> Internal
>
> * further enhance static code analysis by integrating with tool like
> http://types.cs.washington.edu/checker-framework/
>
> > On Mon, Feb 10, 2014 at 7:03 AM, luc <lu...@spaceroots.org> wrote:
> >
> >> Le 2014-02-10 10:16, Thomas Neidhart a écrit :
>
> [snip]
>
> >> Would these annotations only be used as documentation or would there be
> >> some
> >> tools for users?
>
> See above, right now tool support is quite shallow to my knowledge, but
> we have to start somewhere. Ideally, we could create a component that
> contains various annotations that are used by commons (e.g. also
> repackaging Immutable and ThreadSafe from jcip with RetentionPolicy =
> CLASS instead of RUNTIME), and the java ecosystem might start using them.
>
> Thomas
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
Chris
Re: [math] Annotations
Posted by Thomas Neidhart <th...@gmail.com>.
On 02/10/2014 05:44 PM, Chris wrote:
> Hi Thomas,
>
> If this is only for documentary purposes, it seems a bit strange in my
> mind. Wouldn't a comment at the header serve the same purpose?
right now it would mainly be used for documentation purposes as tool
support is not yet there. Instead of browsing through the class javadoc
a user may immediately see the corresponding annotation.
For the future, I see several benefits:
* integrate these annotations in our currently used build-tools, e.g.
clirr could be instructed to ignore classes that are annotated as
Internal
* further enhance static code analysis by integrating with tool like
http://types.cs.washington.edu/checker-framework/
> On Mon, Feb 10, 2014 at 7:03 AM, luc <lu...@spaceroots.org> wrote:
>
>> Le 2014-02-10 10:16, Thomas Neidhart a écrit :
[snip]
>> Would these annotations only be used as documentation or would there be
>> some
>> tools for users?
See above, right now tool support is quite shallow to my knowledge, but
we have to start somewhere. Ideally, we could create a component that
contains various annotations that are used by commons (e.g. also
repackaging Immutable and ThreadSafe from jcip with RetentionPolicy =
CLASS instead of RUNTIME), and the java ecosystem might start using them.
Thomas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Annotations
Posted by Chris <ca...@gmail.com>.
Hi Thomas,
If this is only for documentary purposes, it seems a bit strange in my
mind. Wouldn't a comment at the header serve the same purpose?
-Chris
On Mon, Feb 10, 2014 at 7:03 AM, luc <lu...@spaceroots.org> wrote:
> Le 2014-02-10 10:16, Thomas Neidhart a écrit :
>
>> Hi,
>>
>
> Hi Thomas,
>
>
>
>> 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.
>>
>
> Would these annotations only be used as documentation or would there be
> some
> tools for users?
>
> Luc
>
>
>
>> 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). 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?
>>
>> Thomas
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
Chris
Re: [math] Annotations
Posted by luc <lu...@spaceroots.org>.
Le 2014-02-10 10:16, Thomas Neidhart a écrit :
> Hi,
Hi Thomas,
>
> 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.
Would these annotations only be used as documentation or would there be
some
tools for users?
Luc
>
> 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). 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?
>
> Thomas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Annotations
Posted by Thomas Neidhart <th...@gmail.com>.
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 (
>> 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?
>
> 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.
Thomas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Annotations
Posted by sebb <se...@gmail.com>.
On 11 February 2014 02:12, Chris <ca...@gmail.com> wrote:
> Conversely, adding an annotation would require the addition of features to
> external tool sets and boilerplate to make it work seamlessly, rather than
> just being a nuisance. It's definitely a win some, lose some situation from
> the sounds of it.
If the annotations are only being used to document characteristics of
the code, then there's no need to update tools.
Not sure what you mean by boilerplate.
The annotations would need to be created or added as a dependency.
And the source files would need to be editted, but that is true of
Javadoc, and the size of the edit is likely to be smaller.
> -Chris
>
>
> On Mon, Feb 10, 2014 at 6:14 PM, sebb <se...@gmail.com> wrote:
>
>> The advantage of annotations over Javadoc is that the meaning of each
>> annotation is precisely defined.
>>
>> Javadoc is mainly written in natural language.
>> This much harder to pin down precisely (and harder to parse), unless
>> one defines a convention for how to express the various
>> characteristics of the code that one wishes to document. In which case
>> one might as well use the appropriate annotation.
>>
>> On 10 February 2014 23:01, Phil Steitz <ph...@gmail.com> 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 (
>> >> 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?
>> >
>> > 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.
>> >
>> > 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.
>> >
>> > 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.
>> >
>> > 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.
>> >
>> > Phil
>> >>
>> >> Thomas
>> >>
>> >
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> > For additional commands, e-mail: dev-help@commons.apache.org
>> >
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>
>
> --
> Chris
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Annotations
Posted by Chris <ca...@gmail.com>.
Conversely, adding an annotation would require the addition of features to
external tool sets and boilerplate to make it work seamlessly, rather than
just being a nuisance. It's definitely a win some, lose some situation from
the sounds of it.
-Chris
On Mon, Feb 10, 2014 at 6:14 PM, sebb <se...@gmail.com> wrote:
> The advantage of annotations over Javadoc is that the meaning of each
> annotation is precisely defined.
>
> Javadoc is mainly written in natural language.
> This much harder to pin down precisely (and harder to parse), unless
> one defines a convention for how to express the various
> characteristics of the code that one wishes to document. In which case
> one might as well use the appropriate annotation.
>
> On 10 February 2014 23:01, Phil Steitz <ph...@gmail.com> 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 (
> >> 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?
> >
> > 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.
> >
> > 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.
> >
> > 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.
> >
> > 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.
> >
> > Phil
> >>
> >> Thomas
> >>
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
Chris
Re: [math] Annotations
Posted by Gary Gregory <ga...@gmail.com>.
On Mon, Feb 10, 2014 at 11:01 PM, Phil Steitz <ph...@gmail.com> wrote:
> On 2/10/14, 5:14 PM, sebb wrote:
> > The advantage of annotations over Javadoc is that the meaning of each
> > annotation is precisely defined.
> >
> > Javadoc is mainly written in natural language.
> > This much harder to pin down precisely (and harder to parse), unless
> > one defines a convention for how to express the various
> > characteristics of the code that one wishes to document. In which case
> > one might as well use the appropriate annotation.
>
> Ugh. Shades of the early Wittgenstein. Sorry, could not resist that ;)
>
> Seriously, I see the fact that it is written is natural language as
> an *advantage* of javadoc. Having API documentation deteriorate
> into a sequence of tags with externally defined "meanings" is not
> appealing to me as either a contributor or a user. I know there may
> be a happy medium to be found and I will not stand in the way here.
>
@What's #so #bad #about @annotations? @Especially! when! you! can! Yahoo!
them! #on #the #interwebs?!
G
>
> Phil
> >
> > On 10 February 2014 23:01, Phil Steitz <ph...@gmail.com> 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 (
> >>> 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?
> >> 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.
> >>
> >> 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.
> >>
> >> 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.
> >>
> >> 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.
> >>
> >> Phil
> >>> Thomas
> >>>
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> For additional commands, e-mail: dev-help@commons.apache.org
> >>
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> > .
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
Java Persistence with Hibernate, Second Edition<http://www.manning.com/bauer3/>
JUnit in Action, Second Edition <http://www.manning.com/tahchiev/>
Spring Batch in Action <http://www.manning.com/templier/>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory
Re: [math] Annotations
Posted by Chris <ca...@gmail.com>.
Gonna have to agree with Phil here. In a couple years, when you're digging
through an API and you run into a random annotation that says @Internal,
you're not going to remember why it was. Adding that kind of specificity
would require documentation (Javadoc), which makes the presence of the
annotation pointless to begin with.
-Chris
On Mon, Feb 10, 2014 at 9:01 PM, Phil Steitz <ph...@gmail.com> wrote:
> On 2/10/14, 5:14 PM, sebb wrote:
> > The advantage of annotations over Javadoc is that the meaning of each
> > annotation is precisely defined.
> >
> > Javadoc is mainly written in natural language.
> > This much harder to pin down precisely (and harder to parse), unless
> > one defines a convention for how to express the various
> > characteristics of the code that one wishes to document. In which case
> > one might as well use the appropriate annotation.
>
> Ugh. Shades of the early Wittgenstein. Sorry, could not resist that ;)
>
> Seriously, I see the fact that it is written is natural language as
> an *advantage* of javadoc. Having API documentation deteriorate
> into a sequence of tags with externally defined "meanings" is not
> appealing to me as either a contributor or a user. I know there may
> be a happy medium to be found and I will not stand in the way here.
>
> Phil
> >
> > On 10 February 2014 23:01, Phil Steitz <ph...@gmail.com> 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 (
> >>> 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?
> >> 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.
> >>
> >> 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.
> >>
> >> 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.
> >>
> >> 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.
> >>
> >> Phil
> >>> Thomas
> >>>
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> For additional commands, e-mail: dev-help@commons.apache.org
> >>
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> > .
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
Chris
Re: [math] Annotations
Posted by Phil Steitz <ph...@gmail.com>.
On 2/10/14, 5:14 PM, sebb wrote:
> The advantage of annotations over Javadoc is that the meaning of each
> annotation is precisely defined.
>
> Javadoc is mainly written in natural language.
> This much harder to pin down precisely (and harder to parse), unless
> one defines a convention for how to express the various
> characteristics of the code that one wishes to document. In which case
> one might as well use the appropriate annotation.
Ugh. Shades of the early Wittgenstein. Sorry, could not resist that ;)
Seriously, I see the fact that it is written is natural language as
an *advantage* of javadoc. Having API documentation deteriorate
into a sequence of tags with externally defined "meanings" is not
appealing to me as either a contributor or a user. I know there may
be a happy medium to be found and I will not stand in the way here.
Phil
>
> On 10 February 2014 23:01, Phil Steitz <ph...@gmail.com> 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 (
>>> 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?
>> 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.
>>
>> 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.
>>
>> 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.
>>
>> 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.
>>
>> Phil
>>> Thomas
>>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
> .
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Annotations
Posted by sebb <se...@gmail.com>.
The advantage of annotations over Javadoc is that the meaning of each
annotation is precisely defined.
Javadoc is mainly written in natural language.
This much harder to pin down precisely (and harder to parse), unless
one defines a convention for how to express the various
characteristics of the code that one wishes to document. In which case
one might as well use the appropriate annotation.
On 10 February 2014 23:01, Phil Steitz <ph...@gmail.com> 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 (
>> 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?
>
> 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.
>
> 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.
>
> 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.
>
> 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.
>
> Phil
>>
>> Thomas
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Annotations
Posted by Phil Steitz <ph...@gmail.com>.
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 (
> 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?
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.
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.
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.
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.
Phil
>
> Thomas
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Annotations
Posted by Adrian Crum <ad...@sandglass-software.com>.
On 2/11/2014 4:53 PM, sebb wrote:
> On 11 February 2014 22:40, Thomas Neidhart <th...@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-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Annotations
Posted by Thomas Neidhart <th...@gmail.com>.
Hi sebb,
maybe we should start doing this in a smaller component and then others
might pick up afterwards.
I guess Codec is a good candidate?
Thomas
On Wed, Feb 12, 2014 at 1:53 AM, sebb <se...@gmail.com> wrote:
> On 11 February 2014 22:40, Thomas Neidhart <th...@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;
>
>
> > Thomas
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
Re: [math] Annotations
Posted by sebb <se...@gmail.com>.
On 11 February 2014 22:40, Thomas Neidhart <th...@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;
> Thomas
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Annotations
Posted by Thomas Neidhart <th...@gmail.com>.
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.
Thomas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Annotations
Posted by sebb <se...@gmail.com>.
On 10 February 2014 17:55, Matt Benson <gu...@gmail.com> wrote:
> Version 1.0 of jcip as available from Maven central seems to declare the
> annotations with runtime retention. However, it has always been my
> understanding that missing annotation types, even for those with runtime
> retention, did not cause errors at runtime. I have just verified this by
> creating a simple Maven multimodule project whose main module declares jcip
> as a provided dependency and annotates a class, then uses the annotated
> class from a JUnit test in another module. It is as if the annotation was
> never declared.
This is what we originally thought on HttpComponents.
However a bug was raised [1]
The problem comes when you want to compile against a jar that has
runtime annotations.
With Java 5, you get a compiler error.
With Java 6 you get warnings.
I've not tried this out.
[1] https://issues.apache.org/jira/browse/HTTPCLIENT-866
> Matt
>
>
> On Mon, Feb 10, 2014 at 10:53 AM, sebb <se...@gmail.com> wrote:
>
>> On 10 February 2014 09:16, Thomas Neidhart <th...@gmail.com>
>> wrote:
>> > Hi,
>> >
>> >
>> > Additionally, I would like to introduce also the annotations from the
>> jcip (
>> > 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.
>>
>> AFAIK the JCIP annotations have runtime retention, which means that
>> they need to be available at run-time.
>> That would be quite a nuisance.
>>
>> I did try to get the retention changed to Class file, but failed.
>>
>> However, a quick search just now shows [1] which have classfile retention.
>>
>> [1]
>> http://code.google.com/p/jsr-305/source/browse/trunk/ri/src/main/java/javax/annotation/concurrent/?r=43
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Annotations
Posted by Matt Benson <gu...@gmail.com>.
Version 1.0 of jcip as available from Maven central seems to declare the
annotations with runtime retention. However, it has always been my
understanding that missing annotation types, even for those with runtime
retention, did not cause errors at runtime. I have just verified this by
creating a simple Maven multimodule project whose main module declares jcip
as a provided dependency and annotates a class, then uses the annotated
class from a JUnit test in another module. It is as if the annotation was
never declared.
Matt
On Mon, Feb 10, 2014 at 10:53 AM, sebb <se...@gmail.com> wrote:
> On 10 February 2014 09:16, Thomas Neidhart <th...@gmail.com>
> wrote:
> > Hi,
> >
> >
> > Additionally, I would like to introduce also the annotations from the
> jcip (
> > 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.
>
> AFAIK the JCIP annotations have runtime retention, which means that
> they need to be available at run-time.
> That would be quite a nuisance.
>
> I did try to get the retention changed to Class file, but failed.
>
> However, a quick search just now shows [1] which have classfile retention.
>
> [1]
> http://code.google.com/p/jsr-305/source/browse/trunk/ri/src/main/java/javax/annotation/concurrent/?r=43
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
Re: [math] Annotations
Posted by sebb <se...@gmail.com>.
On 10 February 2014 09:16, Thomas Neidhart <th...@gmail.com> wrote:
> Hi,
>
>
> Additionally, I would like to introduce also the annotations from the jcip (
> 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.
AFAIK the JCIP annotations have runtime retention, which means that
they need to be available at run-time.
That would be quite a nuisance.
I did try to get the retention changed to Class file, but failed.
However, a quick search just now shows [1] which have classfile retention.
[1] http://code.google.com/p/jsr-305/source/browse/trunk/ri/src/main/java/javax/annotation/concurrent/?r=43
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org