commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: [math] Annotations
Date Tue, 11 Feb 2014 02:38:49 GMT
On 11 February 2014 02:12, Chris <cachapline8@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 <sebbaz@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 <phil.steitz@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


Mime
View raw message