[Bioperl-l] API Changes

[Chris Fields]

On Jul 6, 2007, at 10:37 AM, Nathan S. Haigh wrote:

> ...
> Hmm, still not 100% clear - it is Friday!
>
> So, someone running a script that was designed when 1.4 was released
> should still be able to run their script for all future releases.  
> So all
> changes need to be backward compatible?

It helps.  For instance, if we change method names (rename each_Foo  
as next_Foo), we should have each_Foo delegate to next_Foo for the  
time being.  If we plan on deprecating the old method altogether we  
would add a warning message when it's called, then delegate.

It's a better solution than just changing the method outright, which  
means the user has to search through docs to find the renamed method.

> So you have several situations regarding method names:
> 1) Adding new methods should e fine since past scripts don't know  
> about
> them and won't have used them
> 2) Removing methods would break past scripts that used them
> 3) Renamed methods would break past scripts that used the old name
>
> A stable API to me, means the same method calls should still be  
> able to
> accept the same arguments (inc the constructor) and return the same
> object/data etc.

Yes.

> What if a module is pretty outdated and would benefit from a rewrite -
> should all the old method names be included, what if this makes coding
> difficult?

It depends on the module.  If a complete rewrite is needed then maybe  
starting with a new module/interface is best, and we could deprecate  
the older module completely.  That has been done already with  
Bio::Tools::BPLite (in favor of SearchIO) and a few other modules.

>> There are a few methods which are considered deprecated or will be
>> deprecated.  For instance, we recently talked about changes to method
>> names which use case to specify whether you're receiving an object
>> (get_Foo) vs. data (get_foo), a list (get_Foos), a flattened vs.  
>> nested
>> list, or whether to use each_* vs next_* for iterators.   
>> Consistency is
>> nice!
>>
>
> You mean the use of case to signify objects vs data being returned are
> to be deprecated or encouraged? What was the outcome of the each_* vs
> next_*?
>
> Nath

Here's the section I added to the wiki (it started in a thread a few  
weeks or so ago, so it's a summary really):

http://www.bioperl.org/wiki/Advanced_BioPerl#Method_names

Feel free to add to it or make suggestions.

BTWm Hilmar mentioned there was a movement to rename methods in old  
code to follow these recs but it was never completed.  It should be  
taken up again at some point but the recommendations are mainly here  
for newer code.

chris