Advice for naming ado files for SSC

[eric_a_booth]

When writing a package to share on SSC, is it possible (advisable?) to create an abbreviated command syntax?
For example, with official Stata commands like -describe-, we can run -d- , -de-, -des-, -desc-... etc to invoke the same command. (Without any reason to) I always assumed that program syntax had some sort of capitalization convention that would allow for abbreviations (similar to how options are abbreviated) so that programs would look like:

program define  DESCribe
...

to enable abbreviations by the first 4 letters (in the scenario above). However, after looking through my adopath today, I finally realized that there are actually separate ado-files for each potential abbreviation. The abbreviated versions call the main program like:

*! version 1.0.0  27may2004
program d
    /* version intentionally omitted */
    local version : di "version " string(_caller()) ":"
    `version' describe `0'
end

Now to the question. If I wanted to create my own program called -describe2- (for example, I am not actually writing one called this or related to -describe- in any way), could (should?) I submit to SSC the following adofiles to be downloaded with the package for my hypothetical command -describe2- ?

d2.ado
de2.ado
...
describe2.ado 
??

This seems inadvisable, but I'd like to be able to invoke the program I'm writing with both the long command name (which is a better descriptor of the program's purpose) and an abbreviated form (even if it was just two forms: -des2- and -describe2-). Are there better ways to approach this or other examples?

The only solution (workaround) I can think of is to put the -describe2- version on SSC and then write an internal program called -d2- or whatever that calls -describe2- ( but that will require some rewriting of do-files for me and my colleagues who have been using the abbreviated form of the program internally at my organization.)

What about having the main ado-file write the sub-ado files if the user chooses to have them on their system. That is, there would be an option called 'writeabbrev' where if the user ran this at any point:

describe2, writeabbrev

The program would -file write- a new .ado file and put it in the ado-path which contains syntax similar to the code for desc.ado from above. This would activate the ability to use the abbreviation from that point forward (but the first time a user encountered an abbreviated version they would get an uninformative error because desc2 wouldnt exist ). Other thoughts or ideas ?

Thanks!

[daniel klein]

I understand this question here on Statlist as a stimulus for discussion; for an authoritative answer, Eric needs to direct his question to Kit Baum.

I do not believe that it would be a good idea to allow abbreviated commands on SSC. It will get incredibly hard to check for already existing commands with the same (conflicting) names (and abbreviations) and, hence, incredibly hard to come up with new/unique command names. Type

ssc describe d

to get an idea about the number of already existing commands that could be abbreviated d2; it would be a mess.

The same argument applies to an ado-file that creates its own abbreviated version: it does not matter where the file with the abbreviated name comes from; it will enhance the potential for name conflicts.

In general, I do not believe that it is advisable to have multiple abbreviations for one command. It could be argued that two variations are fine, e.g., marginscontplot and mcp (SJ) if one name is really long.

One way to have abbreviated commands is setting up a main ado-file with a short name (possibly even cryptic, say, the initial of the author) and allow abbreviations for various subcommands. Something like

program eab
    version 11.2
    
    gettoken cmd 0 : 0
    
    local len : length local cmd
    
    if ("`cmd'" == substr("describe2", 1, `len')) {
        local cmd describe2
    }
    else if ("`cmd'" == substr("list2", 1, `len')) {
        local cmd list2
    }
    ...
    else {
        display as err "unkonwn subcommand `cmd'"
        exit 198
    }
    
    eab_`cmd' `0'
end

Subcommands could be placed into the same file as sub-routines or into seperate ado-files.

Best
Daniel

[Nick Cox]

I've occasionally allowed abbreviated command names by the device of shorter command names that call up one full command. So, for example

. ssc type circsu.ado
*! NJC 1.0.0 13 Jan 2004 
program circsu
        // no version statement! 
        circsummarize `0' 
end

The user can specify circsu if they so wish; it calls up circcsummarize directly.

I don't allow any possible abbreviation, but that's not a point of principle.

This is emphatically not a problem for SSC as its file structure allows only one file for each distinct name, so Kit Baum would tell someone if a filename was already in use (or better, ssc type would tell the authors in advance).

Command name clashes are undesirable, not desirable, but what's the evidence? Clashes are not a common source of complaint and in any case renaming one offender is easy enough. Thus we messed up at the Stata Journal by not telling one group that the name rdplot was already in use (and they messed up by not checking, but a little deal):

SJ-17-2 st0366_1  . .  rdrobust: Software for regression-discontinuity designs
        . . . . .  S. Calonico, M. D. Cattaneo, M. H. Farrell, and R. Titiunik
        (help rdrobust, rdbwselect, rdplot if installed)
        Q2/17   SJ 17(2):372--404
        describes a major upgrade to the Stata (and R) rdrobust package,
        which provides a wide array of estimation, inference, and
        falsification methods for the analysis and interpretation of
        regression-discontinuity designs

SJ-14-4 st0366  . .  Robust data-driven inference in reg.-discontinuity design
        . . . . . . . . . . . . . S. Calonico, M. D. Cattaneo, and R. Titiunik
        (help rdrobust, rdbwselect, rdplot if installed)
        Q4/14   SJ 14(4):909--946
        conducts robust data-driven statistical inference in
        regression-discontinuity designs

SJ-10-1 gr0009_1  . . . .  Software update for model diagnostic graph commands
        . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  N. J. Cox
        (help anovaplot, indexplot, modeldiag, ofrtplot, ovfplot,
        qfrplot, racplot, rdplot, regplot, rhetplot, rvfplot2,
        rvlrplot, rvpplot2 if installed)
        Q1/10   SJ 10(1):164
        provides new command rbinplot for plotting means or medians
        of residuals by bins; provides new options for smoothing
        using restricted cubic splines; updates anova examples

SJ-4-4  gr0009  . . . . . . . . . . Speaking Stata: Graphing model diagnostics
        . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  N. J. Cox
        (help anovaplot, indexplot, modeldiag, ofrtplot, ovfplot,
        qfrplot, racplot, rdplot, regplot, rhetplot, rvfplot2,
        rvlrplot, rvpplot2 if installed)
        Q4/04   SJ 4(4):449--475
        plotting diagnostic information calculated from residuals
        and fitted values from regression models with continuous
        responses

I'll rename mine officially as soon as anyone makes a fuss about the clash.

[eric_a_booth]

Thanks Daniel and Nick for the feedback. This all makes sense to me. I think I had something in mind that is similar to the -mcp- example Daniel gave (one long name and one abbreviated form), but I also agree that I wouldnt want SSC to become overrun with many abbreviations for user commands. When this is ready to go out the door, I'll Kit for guidance as well.

Side note: I didn't realize that -ssc type- could be used to search for existing SSC names, when I read the description in the helpfile "Type a specific file stored at SSC " I glossed over it because I didnt really understand what the command was _typing_.