17

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. ;-)

  • 3
    A user can probably guess what \setPaperSize could do, \sPS would be a different thing. There is just common sense that will help you in your endeavour. – Johannes_B May 20 at 13:34
  • @Johannes_B Especially regarding package names for CTAN there might be some restrictions/requirements that I am not aware of... – user189337 May 20 at 13:52
  • 3
    TeX packages are just like any piece of software in this respect. There are two hard things in computer science: cache invalidation, naming things, and off-by-one errors. – Seamus May 20 at 13:56
  • 3
    You should take a look at the good practices of other packages. A great example is the egregdoesnotlikesansseriftitles option of KOMA script. – Skillmon May 20 at 14:07
  • 4
    what you suggest sounds reasonable but good practice suggests giving all internal commands a package-specific prefix \mypackage@this, \mypackage@that for example so avoiding clashes with other packages. See also the LaTeX3 naming scheme which formalises many aspects of the command and module names) – David Carlisle May 20 at 14:22
12

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
8

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.)
  • So I guess LaTeX itself is an exception to this rule? :-D – Matthew Leingang May 21 at 19:17
  • 1
    @MatthewLeingang It's LaGacy code. – Alan Munn May 21 at 22:18

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.