R devel - Mar 2003 - formal methods and classes and capitalization conventions

Martin Maechler has suggested that I post this comment to r-devel. It was 
originally posted to bioconductor.

---------------------------------

I'd like to raise the issue of a capitalization convention for naming 
objects in R. Almost everything in R used to be lowercase but recently 
there is increasing use of mixed upper/lower case to define names. There is 
potential for using the capitalizations to make code more self explanatory, 
but only if a consistent system is used.

In Java, capitalization is used to indicate the type of object. Names of 
methods are capitalized except for the first word (e.g., geneNames), names 
of classes are fully capitalized (e.g., ExprSet), names of data objects are 
all lowercase, and names of libraries have their own conventions but 
normally with lowercase letters. A programmer can recognize the type of 
object in many cases simply from the name.

In R, Java capitalization has started to be used for formal generic 
functions, but the point of the convention is lost somewhat because the 
same capitalization is being used for classes, non-generic functions, 
package names and even function arguments. Naming is not always done 
consistently and different conventions seem to be used by different people, 
so within Bioconductor we have classes, functions, arguments, and packages 
with lots of different capitalization styles. One cannot predict what 
capitalization style will be used for a given object, so capitalization is 
on the way to becoming a complication rather than a clarification.

Here is a suggestion for a convention, which people can shoot down if they 
like:

New-style classes: full capitalization, e.g., ExprSet, AffyBatch, MarrayNorm
New-style generic functions: lower case first word, e.g., maNorm, 
normalize, rma, geneNames
Old-style generic functions: leave as they are
Non-generic functions: lowercase, with very sparing use of dot separaters
Members of data classes: lowercase, possibly with dot separaters
Function arguments: lowercase, possibly with dot separaters
Packages: lowercase, e.g., affy, marraynorm

I would be happy myself with almost any convention. What I am looking for 
are guidelines of good practice for a someone developing a new package 
which contains S4 generic functions as well as non-generic functions.

Cheers
Gordon
---------------------------------------------------------------------------------------
Dr Gordon K Smyth, Senior Research Scientist, Bioinformatics,
Walter and Eliza Hall Institute of Medical Research,
1G Royal Parade, Parkville, Vic 3050, Australia
Tel: (03) 9345 2326, Fax (03) 9347 0852,
Email: smyth@wehi.edu.au, www: http://www.statsci.org

Many of us are waiting for _ to become available in names, probably a year 
from now (it will disappear as assignment in 1.8.0: three unreadable bug 
reports this morning show why).  Then other conventions become possible.

The convention you refer to is much older than Java: X11 resources have
similar conventions, and in the Microsoft world this is known as Hungarian 
notation, after Charles Simonyi.

Given that all object names in R are of variant type, type seems less of an 
issue.  (Functions can return different types depending on their arguments 
or even randomly, for example.)


On Wed, 26 Mar 2003, Gordon Smyth wrote:
> Martin Maechler has suggested that I post this comment to r-devel. It was 
> originally posted to bioconductor.
> 
> ---------------------------------
> 
> I'd like to raise the issue of a capitalization convention for naming 
> objects in R. Almost everything in R used to be lowercase but recently 
> there is increasing use of mixed upper/lower case to define names. There is
> potential for using the capitalizations to make code more self explanatory,
> but only if a consistent system is used.
> 
> In Java, capitalization is used to indicate the type of object. Names of 
> methods are capitalized except for the first word (e.g., geneNames), names 
> of classes are fully capitalized (e.g., ExprSet), names of data objects are
> all lowercase, and names of libraries have their own conventions but 
> normally with lowercase letters. A programmer can recognize the type of 
> object in many cases simply from the name.
> 
> In R, Java capitalization has started to be used for formal generic 
> functions, but the point of the convention is lost somewhat because the 
> same capitalization is being used for classes, non-generic functions, 
> package names and even function arguments. Naming is not always done 
> consistently and different conventions seem to be used by different people,
> so within Bioconductor we have classes, functions, arguments, and packages 
> with lots of different capitalization styles. One cannot predict what 
> capitalization style will be used for a given object, so capitalization is 
> on the way to becoming a complication rather than a clarification.
> 
> Here is a suggestion for a convention, which people can shoot down if they 
> like:
> 
> New-style classes: full capitalization, e.g., ExprSet, AffyBatch,
MarrayNorm
> New-style generic functions: lower case first word, e.g., maNorm, 
> normalize, rma, geneNames
> Old-style generic functions: leave as they are
> Non-generic functions: lowercase, with very sparing use of dot separaters
> Members of data classes: lowercase, possibly with dot separaters
> Function arguments: lowercase, possibly with dot separaters
> Packages: lowercase, e.g., affy, marraynorm
> 
> I would be happy myself with almost any convention. What I am looking for 
> are guidelines of good practice for a someone developing a new package 
> which contains S4 generic functions as well as non-generic functions.
> 
> Cheers
> Gordon
>
---------------------------------------------------------------------------------------
> Dr Gordon K Smyth, Senior Research Scientist, Bioinformatics,
> Walter and Eliza Hall Institute of Medical Research,
> 1G Royal Parade, Parkville, Vic 3050, Australia
> Tel: (03) 9345 2326, Fax (03) 9347 0852,
> Email: smyth@wehi.edu.au, www: http://www.statsci.org
> 
> ______________________________________________
> R-devel@stat.math.ethz.ch mailing list
> https://www.stat.math.ethz.ch/mailman/listinfo/r-devel
> 
-- 
Brian D. Ripley,                  ripley@stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595