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 <seb...@gmail.com> 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; > > > > Thomas > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > > For additional commands, e-mail: dev-h...@commons.apache.org > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > >
