Otdfbt

I have written some code which I would like to submit to CTAN as a package for LaTeX 2e. (readme, dtx, ins, pdf with manual and commented sources.)

I need a good name for the package.
Question: Are there guidelines out there for finding good instructive names for LaTeX 2e-packages?

Also the control sequence tokens defined in the package need good instructive names from which the reader can easily deduce the rôle which a control sequence token plays and which do not lead to name-clashes with the kernel/with other packages.
Question: Are there guidelines out there for finding good instructive names for control sequence tokens which one wishes to define within a package?

By now I intend to do as follows:

Macros to be used by the user within the preamble or within the document-environment shall have names which are all in lowercase letters. These names shall enable the user to deduce a) the name of the package where the control sequence in question is defined and b) what the control sequence in question does.

Macros that form some "user interface" for adjustments: Same as above but a mixture of lowercase and uppercase letters. From the macro-name one should also easily deduce which user-level-macros'/document-level macros' workflows are to be influenced by the user-interface-macro/adjustment-macro in question.

Internal macros that form the core of the functionality provided by the package: Same as above, perhaps only lowercase-letters and something from which you can see the "internalness" of the macro in question, and also deduce the author who wrote the macro.

The most crucial point is finding good phrases which are not too long and from which a user can easily deduce what the macro in question does/shall be used for.
Question: Are there guidelines for finding good instructional phrases that can be part of a macro name and from which a user can easily deduce what the macro in question does/shall be used for?

In the first place assume fully expandable macro-based "mechanisms" which in the stage of macro expansion lead to carrying out more or less tricky algorithms and where understanding the algorithm implemented might already be a problem which requires some delving into the matter.

Understanding the interaction of the components which form the implementation should be eased up by instructive macro names...

The point is: In such situations I often end up with macro names which do help me understand things when looking at the code half a year later but which do not help others at all at getting through the things.

Any scheme for macro names I can think of myself makes very long macro names. ;-)

Naming schemes for package internal macros and user macros should be different since they have different purposes.

Internal naming conventions

Internal macros should be named to maximally avoid package conflicts, and secondarily to avoid users from modifying them directly. Most packages and classes use some variant of the following scheme:

• package internal prefix or suffix separated with @. The prefix itself might be based on the package name, or the author's initials or some other scheme that is unlikely to produce a conflict.

For example, I maintain a thesis document class for Michigan State University, and all of the internal macros use the prefix msu@. The naming conventions within the package can be as descriptive as you want. I prefer fairly descriptive names even if they are relatively long since it makes reading the code easier.

• msu@degree


• msu@fieldofstudy

Many authors (especially those who use docstrip) like to use a suffix instead of a prefix, since this makes the index of macros in the documentation more usable. In this case the macros above would be the following. (They would then be indexed under d and f that than all being in a big m list.)

• degree@msu


• fieldofstudy@msu

User macros

The criteria for naming user macros are somewhat different. Depending on the functionality your package provides, naming conflicts may be less of a problem, since two package that provide the same functionality would likely not be used together. But it's best to avoid very generic names which might be used in multiple packages.

The balance between length and descriptiveness is quite subjective. If a macro will be used a lot, a long name is probably inadvisable, but if it's used once in a preamble, length is less of an issue.

Some authors also use the prefix method for user macros too, however, as this dramatically decreases the risk of conflicts. A notable example of this naming scheme is datatool which uses the DTL prefix for all user macros. Here the prefix is upper case to separate it out from the rest of the macro name which is relatively descriptive.

• DTLloaddb


• DTLforeach

The following resources might be of interest to you:

CTAN - Comprehensive TEX Archive Network - How can I up­load a pack­age?

CTAN - Comprehensive TEX Archive Network - Ad­di­tional In­for­ma­tion for CTAN Uploaders, especially the section "Con­di­tions on pack­age ids".

Here you find guidelines and phrases like

e. New pack­ages and bun­dles should not be named af­ter their au­thors,
 but af­ter the pur­pose they are serv­ing, be­cause they may later
 be taken over by other main­tain­ers. (We know that there are a few
 well es­tab­lished CTAN pack­ages that do not ful­fill this rule; but
 that comes un­der “pro­tec­tion of vested rights”, and we have now
 learned from his­tory.)