Re: [agtk-devel] AG API -- list return type

[Steven B. <sb...@un...>]

Folks,

> Steve Cassidy wrote:
> 
> > The compile time switch might be a good way to manage the change 
> > but in the end everyone will be sure to move over given the obvious 
> > need for this.
> 
> Mark Liberman wrote:
> 
> > Another way to manage the change would be to re-name the functions
> > (e.g. "GetAnnotationSetByOffset" -> "GetAnnotationListByOffset")
> > and deprecate the old ones.

I'm online briefly, so let me put in my 2c worth.

I think we're agreed that everyone will want to make the switch.  If it was
a difficult switch to make, such that different projects would have to
allocate time well in advance, then I think Steve's proposal would be
warranted.  However, since the changes to application code are quite
trivial, I think our developers will cope with a sudden switch that comes
from upgrading to a new library version.  The extra work for us in adding
conditional compilation flags throughout our code, plus supporting
documentation, just isn't worth it in my opinion.

As far as the function names go, note that we also have functions called:
GetAnnotationSeqByXXXX (NB Seq not Set).  Thus the function name is clear
about whether the set is ordered or not.  The name "List" is ambiguous to
me, and only provides one name, when we'd need two.  A stronger objection
is that using this name would represent a long-term change to the API
definition, which is not motivating (in my opinion) for such a trivial
change.

> I think both are good ideas.  Are there any opinions as to which of these
> is better?  Perhaps, we can choose one of these two methods, and release
> the new API as version 1.2 or 2.0 quite soon.

So I vote to make a well documented change to the return value of all the
Set and Seq functions, and release it in version 1.2 of the library.  I
vote to hold off on 2.0 until there's much broader experience with the
library among developers in the community.

Steven