[Bioperl-l] API Changes
Chris Fields
cjfields at uiuc.edu
Sat Jul 7 21:17:14 UTC 2007
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
More information about the Bioperl-l
mailing list