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. ;-)
\setPaperSize
could do,\sPS
would be a different thing. There is just common sense that will help you in your endeavour.egregdoesnotlikesansseriftitles
option of KOMA script.\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)