Bioperl: Parameter tag style

[Steve A. Chervitz]

Georg comments:

> You write
> >>>>>>
> $aln = new Bio::Tools::UnivAln(SEQS =>\@seqs);
> <<<<<<
> I guess you modified _rearrange this way -- but it really sucks
> during code development if you can no longer change names by s/seqs/foobar/g
> but need s/SEQS/FOOBAR/g as well -- why not do
> $aln = new Bio::Tools::UnivAln(seqs =>\@seqs);

I didn't modify _rearrange() at all. The statements below are equivalent:
 $aln = new Bio::Tools::UnivAln(SEQS =>\@seqs);
 $aln = new Bio::Tools::UnivAln(-seqs =>\@seqs);

The first thing _rearrange() does is to strip off the hyphens from the 
parameter tags and capitalize them, (so, in principle, I'm saving 
_rearrange() the extra work!). But this brings up a good issue that I would 
like your comments on. I decided to use ALL CAPS for named parameters for 
these reasons:

  1) A naming conflict can occur if a module has a method with the same 
name as a parameter. For example, if I call $fooObj->get(-file=>'readme')
and module Foo.pm defines a sub file {...}, perl may generate a 
warning that it interpreted the -file parameter name as -&file. I say 
"may" because sometimes perl seems to do the right thing and interpret 
-file as '-file'. But I have seen cases where this fails. I haven't 
been able to pin-point why, though (any ideas?). Using ALL CAP tags 
guarantees this ambiguity won't occur (except perhaps for DESTROY). 
Explicitly single quoting all parameter tags is the safest way to go, but is 
cumbersome. 

  2) I find ALL CAP parameter tags to be more readable within code. The 
parameter settings really stand out nicely.

  3) All caps conveys the idea that the tag is a special entity that is 
defined for you. This is consistent with the use of all cap things 
provided by perl (e.g., __END__).

  4) Other modules use the ALL CAP tag convention, though still other 
modules use the -tag convention. I haven't found any recommendation about 
this in the Perl style guidelines (consistent with the "more than one way 
to do it" motto). Honestly, I haven't used enough different modules to get an 
idea for which style is the most widely used. 

Notwithstanding all the above, I feel it is important that all modules 
under the aegis of Bioperl should use the same convention for all public 
methods. Using _rearrange() which supports both parameter naming styles 
is one possiblity, which allows the end user to chose the style that 
works best for them. However, calling _rearrange() for every method would 
be inefficient. Imposing a requirement that all constructors read their 
parameters via _rearrange() (or support both styles some other way) may 
be reasonable. 

Still, there is much to be said for choosing one style and sticking with 
it across all modules. It creates cleaner code and less confusion for users. 
I would argue for the ALL CAP tag style since I find it more readable and 
it solved a problem I had with the -tag style while developing and working 
with my extended module library. 

Opinions welcome!
SteveC

=========== Bioperl Project Mailing List Message Footer =======
Project URL: http://www.techfak.uni-bielefeld.de/bcd/Perl/Bio/
To unsubscribe: send email to majordomo@lists.uni-bielefeld.de with message body
unsubscribe vsns-bcd-perl
Please use the account from which you subscribed, or try:
unsubscribe vsns-bcd-perl <old email-address>
To subscribe: send email to majordomo@lists.uni-bielefeld.de with message body
subscribe vsns-bcd-perl
Administrativa: send email to vsns-bcd-perl-owner@lists.uni-bielefeld.de
====================================================================