[Bioperl-l] Re: mutable accessors

[Juguang Xiao]

On Sunday, January 11, 2004, at 10:16  am, Hilmar Lapp wrote:

> This is a known issue in bioperl. Everybody who is willing to help 
> amend this situation is more than welcome. The problem arises from two 
> facts, both of which you have noticed:
>
> 	- interfaces in bioperl traditionally do not mandate write access, 
> and historically only the read access (i.e., only the mandated part) 
> has been documented
> 	- implementors simply copy&pasted documentation from the interfaces
>
> As we've learned meanwhile, the combination of the two gave rise to a 
> significant hurdle and source of frustration for newcomers, and as it 
> turns out even for old-time users ;)
>
> While the lacking piece of documentation (and hence required 
> guesswork) is fairly straightforward for scalar properties, the 
> problem is aggravated for array properties first by the fact that two 
> different methods need to be used to modify the property (add_XXXX(), 
> and remove_XXXXs()) whose existence would have to be guessed by 
> someone who only reads the interface POD, and second by the existence 
> of different naming conventions for those two mutator methods.

2 points here.

1) Will add_XXXX (singular) accept a list of argument, or only one? In 
some implementation, the developers gave the users convenience to 
accept an array of object silently, which I regard it as the dishonesty 
of method naming. And such convenience will hurt the scalability of 
further development if you want to redefine such add_XXXX method. In my 
experience of reforming Bio::Ontology::Term::add_dblink for the 
InterPro case, add_dblink has been changed to take 2 arguments, that 
the first is the DBLink object, and the second argument is optional, 
called context which to answer the dblink of what, e.g whether the 
dblink is a member of InterPro record or an example of it. the data 
structure looks like

$XXXXs = {
	'~default' => [qw(one two)], # done by add_XXXX('one');add_XXXX('two');
	'context1' => ['three'], # insert by add_XXXX('three', 'context1');
};

2) remove_XXXXs mean to remove all records, which fails to meet the 
occasional requirement if only part of records may be about to be 
deleted. Isn't it a slightly better design that remove_XXXXs may accept 
an array of about-to-delete objects optionally or remove_XXXXs will 
erase all record if the argument list is empty?

One extra point, do you expect these two mutators return something?

Another extra thing that I do not understand. Isn't it nice to 
implement such *regular* mutable accessors in the interfaces in the 
default form? That will save implementors' effort on such duplicate 
coding unless *irregular* and advanced accessors are required and 
created by overriding the default ones.

Juguang