Towards LaTeX Coding Standards Didier Verna
To cite this version:
Didier Verna. Towards LaTeX Coding Standards. TUG 2011 32nd Annual Meeting of the TeX Users Group , Oct 2011, Trivandrum, India. hal-01543098
HAL Id: hal-01543098 https://hal.archives-ouvertes.fr/hal-01543098 Submitted on 26 Jun 2017
HAL is a multi-disciplinary open access L’archive ouverte pluridisciplinaire HAL, est archive for the deposit and dissemination of sci- destinée au dépôt et à la diffusion de documents entific research documents, whether they are pub- scientifiques de niveau recherche, publiés ou non, lished or not. The documents may come from émanant des établissements d’enseignement et de teaching and research institutions in France or recherche français ou étrangers, des laboratoires abroad, or from public or private research centers. publics ou privés. TUGboat, Volume 32 (2011), No. 3 309
Towards LAT X coding standards E - Readability - Maintainability Didier Verna - Robustness - Reliability \relax \keepcool Abstract \takeiteasy Because LATEX is only a macro expansion system, the language does not impose any kind of good software engineering practice, program structure or coding style. Maybe because in the LATEX world, collabo- ration is not so widespread, the idea of some LATEX - Portability coding standards is not so pressing as with other - Extensibility programming languages. Over the years, however, - Intercession the permanent flow of personal development experi- ences contributed to shaping our own taste in terms Figure 1: The coding standards many-festos of coding style. In this paper, we report on all these experiences and describe the programming practices that have helped us improve the quality of our code. 1.1 The coding standards many-festos If one looks at the rationale behind most coding 1 Introduction styles, the intended purpose is always to If the notion of coding style is probably almost as help programmers read and understand old as computer science itself, the concern for style source code, not only their own, but that of in general is even older. An interesting starting others. point is the book “The Elements of Style” [16], first An interesting paragraph from the introductory sec- published in 1918 (the fourth edition appeared in tion of the GNU Coding Standards [15] reads as 1999). This book is a style guide for writing Ameri- follows: can English and has been a source of inspiration for Their purpose is to make the GNU system similar books in computer science later on. It is in- clean, consistent, and easy to install. This teresting to mention the fact that this book has been document can also be read as a guide virulently criticized since its very first publication. to writing portable, robust and reliable Although generally considered as a reference book, programs. the authors were also accused of being condescending in tone and of having only a very partial view on From these widely accepted views on the notion of what proper American English should be. This is coding style, we can draw three different points of already a strong indication that talking about style, view on the subject, as depicted in figure1. whether in natural of programming languages, can Human From the human point of view, using a be quite controversial. Indeed, a style, in large part, proper coding style helps to improve the readability is a matter of personal taste before anything else. of source code, and as a corollary, its maintainability. Consequently, what is considered to be good style by one person can legitimately be viewed as bad style Software From the software point of view, using by another person. a proper coding style helps to make the program The first book on style in programming lan- more robust and reliable. Note that there is a subtle guages was published in 1974 (a second edition ap- but important difference between robustness and peared in 1978) and was entitled “The Elements of reliability. Reliability means that the program should Programming Style” [8], as an explicit reference to do what it is expected to do. Robustness means that its aforementioned predecessor. Although this book the program should handle unexpected situations as was not dedicated to one programming language in gracefully as possible. particular, it was still largely influenced by the few of Man-in-the-middle Third and last, the interme- that time. Since then, numerous books on program- diate point of view is at the interface between hu- ming style appeared, many of them focusing on one mans and programs (note the plural). In this regard, specific language, and being entitled “The Elements the GNU Coding Standards mention the question of of XXX Programming Style” to follow the tradition. portability. This is essentially due to the fact that This includes recent languages such as C#. the GNU project mostly deals with C code, for which portability is indeed an important problem. This,
Towards LATEX coding standards 310 TUGboat, Volume 32 (2011), No. 3
however, is much less of a concern to us because prac- that there is much personal taste in a coding style, tically all LATEX programs are inherently portable consistency means that the exact coding style that (TEX itself being mostly a virtual machine). A much you decide to use is actually less important than the more important question for us is the question of fact of sticking to it. A person not familiar with your extensibility and more generally, intercession. coding style can probably get used to it, provided By extensibility, we mean to answer the follow- that it is used consistently in the whole source code, ing question: given a package that does almost what and that for example, similar situations are identifi- a specific user wants, is it possible to make this able as such because the same idioms are used in all package provide the requested functionality without of them. modifying its internal implementation? If the an- swer is yes, then the package (or at least one of its 1.3 30 years and no style? functionalities) can be said to be extensible. In this Since more or less official coding standards seem to context, one of the purposes of a coding style is to exist for many programming languages and commu- help provide more, and better extensibility. nities, one can’t help but wonder why, after 30 years Unfortunately, full extensibility is only a utopia of existence, the LATEX community still doesn’t have because ultimately, the specific desires of a user are any. Several reasons come to mind. completely unpredictable. In such situations, a pack- age may need to be internally modified. This is 1.3.1 Learning by example what we call “intercession”. The terminology comes LATEX is not a real programming language. It is not from the more general field of so-called “reflexive” even a macro expansion system. LATEX is a library: a languages [10, 14]. Roughly speaking, a reflexive macro layer written on top of TEX. Because of that, language provides the ability to reason about the the purpose of LATEX can be anything you might want program itself (procedural reflection) or even the to do related to typography, which can eventually be language itself (behavioral reflection). Reflection is expressed in terms of TEX. Consequently, it is im- usually decomposed into “introspection” (the ability possible to write “The LATEX programming language” to look at yourself) and “intercession” (the ability book and in fact, this book doesn’t exist. The things to modify yourself). that such a book would have to describe are infinite: While extension is usually a matter of user– they depend on every user’s goal. Note that the package interaction, intercession is usually due to LATEX Companion [12] is not a LATEX programming inter-package interactions. In the LATEX world, we book. For the most part, it describes some of the can identify three major sources of intercession. core functionalities, plus a lot of package features. 1. LATEX core modification: a package needs to This explains why learning by example is an A modify LATEX itself in order to provide the re- important process in the LTEX community. It is quired functionality. quite easy to backtrack from a particular feature to the way it is done: you just need to look at the im- 2. Package inter-compatibility: a package needs to plementation. As a result, many LAT X programmers co-exist with another package, and this requires E (especially newcomers) start by actually looking at modifications in either or both of them. what other people did before us, copy-pasting or im- 3. Package conflict: two (or more) packages inter- itating functionality until they reach a satisfactory cede on the same piece of code but in different level of understanding. In doing so, they also implic- ways, or one package modifies some code and itly (and unconsciously) inherit the coding style (or another package is not made aware of these mod- lack thereof) of the code they are getting inspiration ifications. In both cases, compilation breaks. from. This behavior actually encourages legacy (the Every LATEX user faces the “package conflict night- good and the bad) and leads to a very heterogeneous mare” one day or another [19], to the point that this code base. is probably the major gripe against it these days. Consequently, we would hope that a proper coding 1.3.2 Lack of help style addresses this issue, for example by providing Because it is only a macro library, LATEX is not a design patterns for graceful inter-package compati- structured language but a very liberal one. By pro- bility handling. viding such paradigms as object-oriented, functional, logic, declarative programming, etc., traditional lan- 1.2 Consistency guages provide support for some “elements of style” One final keyword that appears quite a lot in discus- by construction: the choice of a specific program- sions on coding style is “consistency”. Given the fact ming paradigm already imposes a particular design
Didier Verna TUGboat, Volume 32 (2011), No. 3 311
on your program. On the other hand, when you 1.4.1 Tools program in LAT X, you are essentially on your own. E TEX itself provides some facilities for stylish pro- You don’t get any help from the language itself. gramming. The equivalence between blank lines and For the same reason (lack of structure), get- \par encourages you to leave more room in your text, ting help from your favorite text editor is even more therefore improving its readability. TEX also con- complicated. Even theoretically simple things such veniently ignores blanks at the beginning of lines, as indentation can be an editor’s nightmare. In- a crucial behavior when it comes to indenting your denting within braces in a traditional language is code without leaving spurious blanks in the generated relatively simple: it’s a matter of syntactic analysis. output. But suppose that you want to indent the contents A number of packages (e.g. calc and ifthen) A of \if
Towards LATEX coding standards 312 TUGboat, Volume 32 (2011), No. 3
1.5 The need for coding standards pect coding standards to help clean up the current “intercession mess” by providing a set of rules, per- Even though we can explain the lack of LATEX coding standards, and even though some people certainly haps even some design patterns [4, 5, 6, 7, 9, 13] for don’t feel any need for them, we still think that they intercession management. Intercession would become much less of a problem if every package handled it would be a valuable addition to the LATEX world, especially in a much more developed form than what in the same way. we have described in the previous section. Some 1.6 Coding style levels important reasons for this are provided below. Coding standards are supposed to help with writing Learning by good example We have seen ear- better code, although we need to clarify what we lier how LATEX encourages “learning by example”. mean by “better”. In our personal development Obviously, the existence of coding standards would experience, we have identified four abstraction levels help filter out poor quality code and have people at which it is interesting to consider the notion of learn mostly by good example only. style. These four levels, which we are going to explore Homogeneity We have also seen how a plethora in the next sections, are the following. of small packages with no coding style, or author- 1. Layout (low). At the layout level, we are in- specific ones only, contributes to make LATEX a very terested in code formatting, indentation, macro heterogeneous world. This is the point at which it naming policies, etc. is important to make a distinction between coding 2. Design (mid). The design level deals with im- style and coding standards. A coding style can be plementation: how you do the things that you do. seen as a set of personal tastes and habits in terms This is where we address software engineering of programming. A coding standard, by extension, concerns such as modularity, encapsulation, the should be defined as a coding style which multiple potential use of other programming languages’ people agree to conform to. paradigms, etc. A In spite of the anti-social aspect of LTEX devel- 3. Behavior (high). The behavior level is con- opment, that is, even if independent package develop- cerned with functionality as opposed to imple- ers rarely talk to each other, we know that the very mentation: what you do rather than how you do A high level of intercession in LTEX implies that devel- it. At this level, we are interested in user inter- opers are forced to read and understand other peo- faces, extension, intercession (notably conflict ple’s code. In that context, it becomes apparent that management), etc. having more-or-less official coding standards would 4. Social (meta). Finally, the social level is a meta- make it easier for people to read and understand level at which we consider human behavior in others’ code. Homogeneity facilitates interaction. the LAT X community. Notions like reactivity One important problem here is that a consensus E and open development are examined. never comes without any concession. Coming up with coding standards that would satisfy everyone 1.7 Target audience is highly unlikely, given the importance of personal In the LATEX world, it is customary to distinguish taste, even if those coding standards leave room for the document author, writing mostly text, from the some degree of flexibility. The question that remains package author (or LATEX developer) writing mostly open is hence the following: to what extent would macros. Those two kinds of audience slightly over- people agree to comply with coding standards that lap, however. By providing automatically generated diverge from their own habits or preferences, if it is text (e.g. language-dependent), the package author for the greater good of the community? is a bit of a document author. By using packages, Intercession There are many other reasons why fixing conflicts between them and providing personal having coding standards would be a plus. Inter- macros in the preamble, the document author is also cession is another very important one. The way a a bit of a LATEX developer. While this paper is mostly particular package handles a particular typesetting targeted at the package developer, many concerns problem only affects itself: both the problem and the expressed here (most notably at level 1: layout) are solution are localized. The situation is however very also very important for the document author. different when it comes to intercession. The way a particular package handles an extension or a conflict 2 Level 1: Layout (for example by applying dynamic modifications to In this section, we explore the first level of style, another package or to the LATEX kernel) does affect dealing with visual presentation of source code and the outside world. As a consequence, one would ex- lexico-syntactic concerns such as naming conventions.
Didier Verna TUGboat, Volume 32 (2011), No. 3 313
2.1 Formatting code sequence) which makes sense as a whole. In tra- One very important concern for readability is the way ditional programming languages, a logical instruction you visually organize your code. Most of the time, is generally a function call along with its arguments, A this boils down to a simple question: how and where or an operator along with its operands. In LTEX, do you use blanks. This question is more subtle to the situation is more complicated, notably because of the throes of macro expansion. address in LATEX than in other, more syntactically structured languages. We have identified four rules Perhaps it is simpler to make this point by pro- which contribute to better formatting. viding some examples. We assume here that our logical instructions are small enough to fit on one 2.1.1 The rules line, the idea being to avoid putting two of them Rule #1: Stay WYSIWYG’ly coherent next to each other. LATEX (or TEX, for that matter) has bits of pseudo- \hskip.11em\@plus.33em\@minus.07em WYSIWYG behavior. The fact that a blank line ends This line constitutes only one logical instruction be- a paragraph is one of them. There are also some cause the sequence of macros and quantities define a commands whose effect can be directly simulated in single length. your source code (or document). In such situations, {\raggedleft\foo\bar baz\par} it is probably a good idea to do so. Here, the flushing instruction applies until the clos- The two most prominent examples of this are ing brace (assuming the paragraph ends before the the \\ and \par commands. Since \\ effectively group), so it would be strange, for instance, to go ends the current line, we find it reasonable to do to the next source line after \bar. Note however so in the source file as well. Put it differently: we that for longer contents, not fitting on one line only, find it confusing when a \\ command is immediately we would probably go to the next line right after followed by text or code that produces text. The \raggedleft, so that the formatting instruction(s) same goes for \par, with an additional remark: we are distinct from the text to which they apply. have seen code in which \par is followed by some In the same vein, it would be unwise to split text, with the explicit intention of beginning a new things like \expandafter\this\that, conditional paragraph. Although ending a paragraph can, in terms such as \ifx\foo\bar, and more generally, some circumstances, be equivalent to beginning the everything that can be regarded as an argument to next one, this use of \par is extremely confusing what precedes. because the its semantics are precisely to end the current paragraph. Rule #4: Indent all forms of grouping Tabular-like environments are another situation This rule is probably the most obvious, and at the in which it can be nice to mimic the actual output same time the most important, when it comes to layout. Although it requires a fair amount of work, readability. All forms of grouping should have their probably without the help of your favorite text edi- contents indented so that the beginning and end of tor, aligning the various tab commands or columns the groups are clearly visible. It seems that indent- separators across rows helps readability. If, as we ing by 2 columns is enough when you use a fixed do, you prefer to remain within the bounds of 80 width font, whereas 4 or 8 columns (or a tab) are columns, a compromise may be necessary between necessary otherwise. In general however, using tab both constraints. characters for indentation is inadvisable (notably in document sources, but sometimes in package sources Rule #2: Be “spacey” in math mode as well). Tabs can be dangerous, for instance, when Surprisingly enough, it seems that many people for- you include code excerpts that should be typeset in get that spaces don’t count in math mode. This is a a special way. good opportunity to take as much room as you want In LATEX, grouping can occur at the syntactic and make your equations easier to read. Consider level with group delimiters ({}, []) or math modes the following two alternatives. This: ($ and \(\), $$ and \[\]), and also at the semantic $ f(x) = f(x-1) + f(x-2) $ level (\bgroup / \egroup, \begingroup / \endgroup is probably better than this: or even \makeatletter / \makeatother). Your fa- vorite text editor will most likely help you indent at $f(x)=f(x-1)+f(x-2)$ the syntactic level, but you will probably need to Rule #3: One “logical” instruction per line do some manual work for semantic grouping. In the This rule may be a wee bit fuzzier than the previous case of Emacs for example, manually indenting the ones. By “logical”, we roughly mean something (a first line below a call to \makeatletter is usually
Towards LATEX coding standards 314 TUGboat, Volume 32 (2011), No. 3
1 %% Original version: 2 \def\@docinclude#1 {\clearpage 3 \if@filesw \immediate\write\@mainaux{\string\@input{#1.aux}}\fi 4 \@tempswatrue\if@partsw \@tempswafalse\edef\@tempb{#1}\@for 5 \@tempa:=\@partlist\do{\ifx\@tempa\@tempb\@tempswatrue\fi}\fi 6 \if@tempswa \let\@auxout\@partaux \if@filesw 7 \immediate\openout\@partaux #1.aux 8 \immediate\write\@partaux{\relax}\fi 9 % ... \fi :-( 10 11 %% Reformatted version: 12 \def\@docinclude#1{% 13 \clearpage 14 \if@filesw\immediate\write\@mainaux{\string\@input{#1.aux}}\fi 15 \@tempswatrue 16 \if@partsw 17 \@tempswafalse 18 \edef\@tempb{#1} 19 \@for\@tempa:=\@partlist\do{\ifx\@tempa\@tempb\@tempswatrue\fi}% 20 \fi 21 \if@tempswa 22 \let\@auxout\@partaux 23 \if@filesw 24 \immediate\openout\@partaux #1.aux 25 \immediate\write\@partaux{\relax}% 26 \fi 27 % ... \fi :-) Figure 2: The virtues of proper formatting
enough to have the subsequent ones follow the same \newenvironment{env} indentation level automatically. But then again, you {\opening\code will also need to manually unindent the closing call \opening\code} to \makeatother. {\closing\code As an illustration of both rules #3 and #4, \closing\code} consider the code in figure2 in both original and We find this kind of formatting somewhat odd and it reformatted form. In each case, ask yourself: to doesn’t seem to be used so frequently anyway. The which conditional does the upcoming \fi belong? conspicuous amount of indentation can be disturbing, This point clearly demonstrates the importance of and it is also a bit difficult to visually distinguish indentation. Line 14 contains an example of what the opening argument from the closing one. we called a “logical” instruction, although a longer A more frequent way of formatting this would one this time. The contents of the conditional is a be more or less as in a piece of C code, as follows: single instruction to write something in the auxiliary \newenvironment{env} file immediately. Also, since there is no \else part {% in this conditional and the whole line doesn’t exceed \opening\code 80 columns, we chose to keep it as a one-liner. The \opening\code same remark can be made for line 19. } {% 2.1.2 Formatting of syntactic groups \closing\code In the case of syntactic groups, various policies can \closing\code be observed regarding the position of the braces (this } is also true in other programming languages). The This kind of formatting is admittedly more readable, case of an environment definition could be formatted although the two nearly empty lines between the as follows, as is done on several occasions in the opening and the closing arguments may be considered LATEX standard classes: somewhat spurious. Some people hence take the
Didier Verna TUGboat, Volume 32 (2011), No. 3 315
\newcommand\text{% opening and closing instructions may themselves be \@nextentry the result of macro expansion). When possible, it is a \noalign\bgroup good idea to preserve the amount of indentation cor- \gdef\@beforespace{...}% responding to the current group nesting level, even if \@ifstar{\@stext}{\@text}} the group in question is not syntactically apparent. Consider for example the code in figure3 taken \newcommand\@text[1]{% from the C rV class [17]. The \text command calls \gdef\@nextentry{}% u e , but the argument passed to \egroup% end of \noalign \noalign \noalign \multicolumn{3}{@{}p ... \\}} (enclosed in \bgroup/\egroup) starts here and ends in either \@text or \@stext. You can see that this \newcommand\@stext{% group’s indentation level is preserved across all three \gdef\@nextentry{\egroup\\\par}% macros. \egroup% end of \noalign \multicolumn{3}{@{}p ...} ...} 2.1.4 Exceptional situations No rule goes without exception. Sometimes, and for Figure 3: Inter-macro indentation the greater good, one might be tempted to go against the established rules. Here are two examples. habit of joining those two lines as follows: Consider the following call to \@ifnextchar: \newenvironment{env} \@ifnextchar[%] syntax screwup! {% {\@dothis}{\@dothat} \opening\code The left square bracket, which is in fact the first \opening\code argument of \@ifnextchar, confuses Emacs because }{% \closing\code it thinks it’s the opening of a group, and expects \closing\code this group to be closed somewhere. In order to } compensate for this problem, we usually virtually close the fake group by putting a right square bracket Other people choose a more compact formatting within a comment on the same line. This forces us, by closing a group, and possibly opening the next however, to provide the “then” and “else” arguments one on the same line, as follows: to \@ifnextchar on the next line, something that \newenvironment{env}{% we would normally not do. \opening\code Another exceptional situation is the case of \opening\code}{% empty macro arguments, where we prefer to stay \closing\code \closing\code} on the same line rather than consuming another one just for an empty pair of braces, as illustrated below: Again, this leads to quite compact code that makes it difficult to visually distinguish the opening \@ifundefined{#1note}{}{% argument from the closing one. In such a case, a \@fxpkgerror{a short explanation}{% possible workaround is to introduce comments, also a longer one}} an opportunity for documenting the macro’s proto- 2.1.5 Corollary type (imagine that in a text editor with fontification, you might also have different colors for code and As a corollary to the rules described in this section, comments): it is essential to note that the % character is your “worst best friend”. A very important problem when \newenvironment{env}{% %% \begin{env} writing macros (and even documents) is the risk of \opening\code spurious blank spaces. When you indent your code \opening\code}{% properly, many blanks are inserted, which are not %% \end{env} supposed to appear in the final document. TEX helps \closing\code you with that in several ways: spaces are eaten after \closing\code} a control sequence, consecutive blanks are treated as only one (this includes the newline character), and 2.1.3 Inter-macro indentation leading / trailing spaces are discarded on every line. The case of semantic grouping introduces an addi- That alone, however, is not sufficient for a liberal tional level of complexity because groups may be indentation scheme. In the previous examples, we opened and closed in different macros (worse: the have seen many places (notably after braces) where
Towards LATEX coding standards 316 TUGboat, Volume 32 (2011), No. 3
it is required to create an end-of-line comment with and perform similar, very general tasks, although the % character, so that the final newline character is in different ways. It would hence be silly to have not taken as a textual one (see for example figure3 to name similar things differently (imagine for in- on the previous page). stance that the sectioning commands were named In that sense, the % character is your best friend. \artsection, \rprtsection and \bksection!). On It is also your worst friend because determining the the other hand, the risk of collision is still high, pre- exact places at which an end-of-line comment is re- cisely because of the broad spectrum of class func- quired is far from trivial. There are even cases where tionality. This problem has already befallen us in it could be necessary after opening an environment the CurVe class, which provides a \text macro, also in a final document! In any case, when there are implemented (to do something different) by siunitx blanks in your source that you know you don’t want and probably other packages. \text is the perfect in the output, and you’re unsure whether TEX will example of a very poor choice of name because it skip them on its own, you can safely always insert a is far too general and doesn’t really mean anything. comment character at the end of the line. This demonstrates that choosing a pertinent, unique and concise name for a macro is an important but 2.2 Naming tricky exercise. The second concern we want to address in this section Rule #2: Use postfixes is that of naming schemes. Naming conventions are In a very analogous way, there are situations in which obviously important for readability, but also for back- the use of a postfix may be a good idea in order to ward compatibility. Once you get a name, it’s for life. avoid name clashes, although this time not with other Starting with bad naming conventions can become packages, but with yourself. LATEX provides a number a major headache, both for your clients (using your of concepts, loosely related to data types or struc- API) and yourself (maintaining your own code). tures, such as counters and saveboxes. Unfortunately, 2.2.1 The rules the provided interfaces are rather inconsistent. In some situations like counters, you are only Rule #1: Use prefixes required to provide a name, and LATEX constructs the Because LATEX lacks a proper notion of module, pack- underlying, opaque macros with a specific naming age, or even namespace, the use of a specific prefix scheme. What’s more, you are not supposed to for every package that you write should be a rule of use those macros explicitly. Suppose for example thumb. For example, our FiXme [18] package uses fx that you want to maintain a counter of “items”. as a prefix, which means that every command (but There is no need to name this counter myitemscount see rule #3) starts with those two letters. because the standard interface makes things perfectly The choice of the prefix is also important. In readable without the postfix: theory, the prefix that would guarantee a minimal \newcounter{myitems} risk of name clash between packages would be the ... \value{myitems} % not a very good name full package name. In practice however, this can ... \stepcounter{myitems} lead to very long macro names, cumbersome to type. Therefore, a trade-off must be made between the Besides, the risk of name clash is minimal because prefix length and its uniqueness (a possible idea is to under the hood, LATEX has used a specific and hope- start by removing the vowels). fx for example has fully unique naming scheme for naming the counter the defects of its qualities: it is practical because it macro (\c@myitems). is very short, but the risk of collision with only two Suppose now that you want to save your items letters is not negligible. in a box. In that case, you are requested to provide Once you have chosen a prefix, it is also im- a macro name yourself, and choosing \myitems is portant to stay consistent and stick to it. Recently, for sure a bad idea because that name is too general we discovered that for some obscure (and forgotten) (there is no indication that you’re talking about the box of them, and not the number, list or whatever reason, our FiNK package uses a prefix of fink for its user-level commands, but only fnk for its internal else of them). What you need to do, therefore, is ones. This is not only rinadvisable but also unneces- decide on a specific naming scheme for boxes, just A sary since LATEX already provides the @ character con- as LTEX does under the hood for counters. Using a vention for making such a distinction (cf. rule #3). box postfix appears to be a good solution: One situation where the prefix rule should prob- \newsavebox\myitemsbox ably be relaxed is the case of classes (as opposed to ... \savebox\myitemsbox{...} styles). Classes, by definition, are mutually-exclusive ... \sbox\myitemsbox{...}
Didier Verna TUGboat, Volume 32 (2011), No. 3 317
Of course, there is some naming redundancy in this \DeclareRobustCommand\fxnote{% code, but that is what you get from an interface that %% ... is not as opaque as it should be. \@ifstar{% If you are developing a package (as opposed %% \fxnote* to a document) and want to maintain an internal \@ifnextchar[%] list of items, you may also be tempted to follow {\@fxsnote{#2}} {\@@fxsnote{#2}}}{% LAT X’s own convention for, say, counters, and call E %% \fxnote your macro or something like that. We \b@myitems \@ifnextchar[%] advise against that, however, because it conflicts with {\@fxnote{#2}} the prefix rule described previously, and also because {\@@fxnote{#2}}}} it would make your code less readable (remember that you need to use the macro explicitly, not just \long\def\@fxsnote#1[#2]#3#4{% the “name of the thing”). %% ... Finally, note that the ultimate solution to this \@@fxsnote{#1}{#3}{#4}} kind of problem would be to develop another, prop- erly abstracted layer on top of the original one, in \long\def\@@fxsnote#1#2#3{% which the actual macro names are never used explic- \implement\me} itly, and standardize on it. . . Figure 4: Nesting levels
Rule #3: Obey the Companion The LATEX Companion provides some advice on nam- • as a prefix to indicate an internal implementa- ing in section A.1. Modulo a substantial amount of tion of an external functionality, legacy code, LATEX itself tries to adhere to the nam- • as a word separator. ing conventions described there so it is a good idea For example, the current (language-dependent) to honor them in your packages as well. For starters, value for the “List of FiXme’s” section name is stored you are invited to name your external macros with in a macro named \@fxlistfixmename (an accept- lowercase letters only, and reserve a mixture of lower- able alternative would be \fx@listfixmename). case and uppercase names for extension APIs. FiXme, In some situations, the implementation of a par- for example, follows this convention by providing ticular feature may go through different levels of an end-user command named \fxuselayout, and indirection. In such cases, we like to use multiple @ at the same time an equivalent command named characters to give an indication of the current imple- \FXRequireLayout for theme authors. mentation level. Figure4 illustrates this. The macro The other important and well known naming \fxnote supports an optional * postfix as well as a convention adopted by LATEX is the use of an @ char- regular optional first argument provided in square acter in internal macro names. By turning this char- brackets. The implementation goes through a first acter into a letter (category code 11) only internally sub-level that detects the presence of a * charac- and in packages, LATEX effectively prevents the docu- ter (\@fxnote / \@fxsnote), plus another sub-level ment author from using such macros directly (one which handles the presence of an optional argument would have to intentionally enclose a call to an @- (\@@fxnote / \@@fxsnote). macro within \makeatletter / \makeatother). A final example is the case of “polymorphic” Third-party packages should obviously follow macros (see section 3.3 on page 319), that is, macros this convention in order to separate internal from whose implementations depend on some context. As external macros. Package authors should however mentioned earlier, the @ character can be used to do a better job at naming internal macros than separate words. For instance, FiXme has a macro LATEX itself (again, we see here the effect of a long named \@@@fxnote@early. This macro is polymor- legacy). The LATEX kernel seems to enjoy making phic in the sense that its actual implementation fun of the @ character, using it in place of different varies according to the document’s draft or final vowels (e.g. \sixt@@n or \@filef@und) and with no mode. The two corresponding effective implemen- apparent rationale in terms of number and position tations are named \@@@fxnote@early@draft and (e.g. \@input, \@@input but \@input@). \@@@fxnote@early@final. Although we underst@nd how this c@n be fun, it is better for readability to keep a more systematic ap- 2.2.2 Exceptional situations proach to naming internal macros. Typically, we find From time to time, the naming rules exhibited in that using the @ character is useful in two situations: the previous section may be bypassed for the sake of
Towards LATEX coding standards 318 TUGboat, Volume 32 (2011), No. 3
readability. Here are three typical situations where 3 Level 2: Design exceptions are in order. In this section, we explore the second level of style, dealing with design considerations such as modularity Conforming to de facto standards LATEX it- self has some naming conventions that may impact and other programming paradigms. From a more a package or even a document author. Lists are one practical point of view, design here is concerned with such case. For example, the behavior for the list of fig- how to implement a particular feature, rather than the feature itself. ures depends on two macros named \listoffigures and \listfigurename. FiXme supports its own 3.1 Rule #1: Don’t reinvent the wheel list facility, and for the sake of coherence, provides analogous macros named \listoffixmes (instead 3.1.1 Feature libraries of \fxlist or some such) and \listfixmename (in- In many programming languages, so-called “stan- stead of \fxlistname). Following the usual conven- dard libraries” provide additional layers of function- tion makes it much easier for your users to remember ality, typically functions that perform useful and your own API. frequently needed treatments. Browsing CTAN [2] Another example is that of conditionals. All clearly demonstrates that LATEX is no exception to conditionals in (LA)TEX are named \ifhsomethingi. this rule. People have created packages for making So here again, given that you need to implement slides, curricula vitae, split bibliographies, tables mycondition, it is better to name your conditional that span across several pages, etc. \ifmycondition than \myifcondition. When you develop a package, it is important, although not trivial, to be aware of what’s already Forced exceptions There are times where LAT X E existing in order to avoid reinventing the wheel. For itself will force you to depart from your own rules, instance there are currently at least half a dozen dif- although this is seldom critical. The case of counters ferent solutions for implementing key-value interfaces is one of them. When creating a counter for myitems, to macros (keyval, xkeyval, kvoptions, pgfkeys, LAT X creates a macro named \c@myitems which is E etc.). This is very bad because each solution has its not how you would have named this macro. However, own strengths and weaknesses, so the choice of the this is not such a big deal because in general, you most appropriate one for your personal needs can be don’t need to use this macro directly. very complicated and time-consuming (in fact, there A slightly more intrusive exception is when might not even be a best choice). LAT X requires that you implement a specific macro, E One rule of thumb is that when you feel the need following its own naming scheme. For instance, sup- for implementing a new functionality, someone most porting a list of FiXme’s involves implementing a probably had the same idea before you, so there is macro named \l@fixme. The l@ prefix is LAT X’s E a good chance that you will find a package doing choice, not ours. something close to what you want. In such a case, it Finally, if you implement an environment named is better to try and interact with the original author myenv,LAT X will eventually turn this into a macro E rather than to start over something new on your named \myenv and another one named \endmyenv. own. Doing this, however, also requires some rules in Here again, the names are LAT X’s choice, not yours. E terms of social behavior (cf. section 5 on page 326). And by the way, it is unfortunate that the envi- ronment opening macro is not named \beginmyenv 3.1.2 Paradigm libraries instead of just \myenv because it means that you can’t have both a command and an environment Furthermore, in the LATEX world the notion of stan- with the same name. In the FiXme package, we dard library goes beyond common functionality: it use a nice naming trick for this kind of situation: goes downwards to the language level. TEX was not environments corresponding to macros are prefixed originally meant to be a general purpose program- with “a” or “an”. For example, there is a macro ming language, but TEX applications today can be named \fxnote and the corresponding environment so complex that they would benefit from program- is named anfxnote. This contradicts our own nam- ming paradigms normally found in other languages. ing conventions but it makes the actual environment Because of this, there are packages that are meant usage as readable as if it were plain English: to extend the language capabilities rather than pro- viding a particular (typesetting) functionality. The \begin{anfxnote} two most prominent examples of this are calc and ... ifthen. These packages don’t do anything useful \end{anfxnote} in terms of typesetting, but instead make the pro-
Didier Verna TUGboat, Volume 32 (2011), No. 3 319
grammer’s life easier when it comes to arithmetic 3.2.2 Copy-paste calculations or conditional branches. Another one, Consider again the case of FiXme which defines sev- called record, even goes as far as providing data eral Boolean options. For each Boolean option foo, A structures for LTEX. FiXme also provides a corresponding nofoo option, It is always a good idea to use these packages as a shortcut for foo=false. E.g. the langtrack / rather than doing things at a lower level, or re- nolangtrack option can be defined as follows: inventing the same functionality locally. The more \@fxdefineboolkey{lang}{langtrack}[true]{} abstract your code, the more readable. The LAT X E \@fxdefinevoidkey{lang}{nolangtrack}{% Companion advertises some of them (notably calc \@nameuse{fx@lang@langtrack}{false}} and ifthen). Of course, the difficult thing is to be- Defining the silent / nosilent option can be come aware of the existence of such packages (CTAN contains literally thousands of packages). lazily done by copy-pasting the previous code and only modifying the relevant parts (the option and 3.2 Rule #2: Duplication/Copy-paste is evil family names): This rule is well-known to every programmer, al- \@fxdefineboolkey{log}{silent}[true]{} though the “evilness” threshold may be a bit subtle \@fxdefinevoidkey{log}{nosilent}{% to calculate. It is also interesting to provide some \@nameuse{fx@log@silent}{false}} insight on the distinction we make between “dupli- This way of doing things obviously screams for ab- cation” and “copy-paste”. The two examples below straction. It is better to make the concept of “ex- will shed some light on these matters. tended Boolean” explicit by providing a macro for creating them: 3.2.1 Duplication \newcommand*\@fxdefinexboolkey[3][]{% Consider the case of FiXme which uses the xkeyval \@fxdefineboolkey{#2}{#3}[true]{#1} package for defining several layout-related package \@fxdefinevoidkey{#2}{no#3}{% options. The bad way of doing it would be as follows: \@nameuse{fx@#2@#3}{false}}} \define@key[fx]{layout}{morelayout}{...} \define@cmdkey[fx]{layout}{innerlayout}{...} \@fxdefinexboolkey{lang}{langtrack} \define@key[fx]{envlayout}{envlayout}{...} \@fxdefinexboolkey{log}{silent} This is bad because the [fx] optional argument (the 3.3 Rule #3: Conditionals are evil prefix in xkeyval terminology) is duplicated in every This rule may sound surprising at a first glance, single call to the xkeyval package (and it is rather but experience proves that too many conditionals easy to forget). can hurt readability. In fact, this is well known This is a typical case where duplication should in the object-oriented community. After all, object- be abstracted away in order to avoid redundancy. We orientation is essentially about removing explicit con- can improve the code by providing wrappers around ditionals from code. xkeyval as follows: There are two main reasons why conditionals \newcommand\@fxdefinekey{\define@key[fx]} should be avoided whenever possible. \newcommand\@fxdefinecmdkey{\define@cmdkey[fx]} • First, too many conditionals, especially when \@fxdefinekey{layout}{morelayout}{...} \@fxdefinecmdkey{layout}{innerlayout}{...} they are nested, make the program’s logic diffi- \@fxdefinekey{envlayout}{envlayout}{...} cult to read. It should be noted that this new version is actu- • Second, the presence of multiple occurrences of ally longer than the previous one. Yet, it is clearer the same conditional at different places is a form because more abstract. Using such wrappers is like of duplication, and hence should be avoided. saying “define a FiXme option”. This is more abstract One particular design pattern that helps a lot in than “define an option which has an fx prefix”. removing explicit conditionals is to centralize the Note also that in this example, two “layout” logic and use polymorphic macros. This is explained options are defined. One could hence be tempted to with the following example. abstract the layout family, for example by providing Figure 5 on the next page implements a macro an \@fxdefinelayoutkey command. We decided \doeverything, the behavior of which depends on not to do this but it could be a legitimate choice. whether the document is in draft or final mode. This This is an illustration of the flexibility and perhaps macro is in fact decomposed in three parts: the “do also the difficulty there is to decide on the exact this” part, a middle part (left as a comment) and a “evilness duplication threshold” mentioned earlier. final “do that” part. Because the same conditional
Towards LATEX coding standards 320 TUGboat, Volume 32 (2011), No. 3
\newif\ifdraft \def\dothis@draft{\this\way} \def\dothis@final{\this\other\way} \def\doeverything{% \ifdraft \def\dothat@draft{\that\way} \dothis\this\way \def\dothat@final{\that\other\way} \else \dothis\this\other\way \def\doeverything{% \fi \dothis %% ... %% ... \ifdraft \dothat} \dothat\that\way \else \DeclareOption{draft}{ \dothat\that\other\way \let\dothis\dothis@draft \fi} \let\dothat\dothat@draft} \DeclareOption{final}{ \DeclareOption{draft}{\ifdrafttrue} \let\dothis\dothis@final \DeclareOption{final}{\ifdraftfalse} \let\dothat\dothat@final} \ExecuteOptions{final} \ExecuteOptions{final} \ProcessOptions \ProcessOptions
Figure 5: Conditional duplication Figure 6: Centralized logic
branch clutters the code in two different places, the three-step nature of this macro is not very apparent. 3.4 Rule #4: Be modular A better and clearer implementation of the same Modularity is another final principle which is rather functionality is proposed in figure6. Here, the two obvious to follow, although it is perhaps even more mode-dependent parts of the \doeverything macro crucial in LATEX than in other programming lan- are explicitly implemented in different macros, with guages. Modularity affects all levels of a document, a postfix indicating in which mode they should be from the author’s text to the packages involved. used. In the \doeverything macro, the three parts At the author’s level, it is a good idea to use are now clearly visible. This new version of the macro LATEX’s \include command and split your (large) is obviously much more concise and readable. The source files into separate chunks. When used in important thing to understand here is that when conjunction with \includeonly, compilation may you read the code of \doeverything, you are in fact be considerably sped up by making LATEX process not concerned with implementation details such as only the parts on which you are currently working. how \dothis and \dothat vary according to the From a package development perspective, mod- document’s mode. It is more important to clearly ularity is important at different levels. In terms of distinguish the three steps involved. distribution, the docstrip package is an essential Finally, you can also note that the logic involving component in that it allows you to split your source conditionals is centralized at the end, where the code into separate files, provides conditional inclu- actual draft or final options are processed. As a sion and (and perhaps most importantly) lets you side note, the \ifdraft conditional is not needed generate separate distribution files from a centralized anymore and the total amount of code is smaller in source. This is important because splitting a package this new version. This time, clarity goes hand in across different files allows you to subsequently load hand with conciseness. only the relevant ones. Less code loaded into LATEX You may still be wondering what we meant by means reduced memory footprint and improved per- “polymorphic macros”. Although slightly abusive, formance. Imagine for instance if Beamer had to this term was coined because of the resemblance of load every single theme every time it is run! this design pattern with object-oriented polymor- At a lower level, the modularity principle dic- phism, encountered in virtual methods `ala C++ or tates that it is better to have 10 macros of 10 lines generic functions `ala Lisp. The macros \dothis each rather than one macro of 100 lines. Every pro- and \dothat are polymorphic in the sense that they grammer knows this but perhaps LATEX programmers don’t have a regular implementation (in other words, don’t realize that this is even more critical for them. they are only virtual). Instead, their actual imple- There is indeed one LATEX-specific reason for keeping mentation varies according to some context. your macros small. That reason is, again, interces-
Didier Verna TUGboat, Volume 32 (2011), No. 3 321
sion. Since other package developers may need to One of the major pitfalls to avoid when writing tweak your code for compatibility reasons, it is bet- documentation is forgetting that a user manual is not ter to let them work on small chunks rather than big the same thing as a reference manual. Just doing lit- ones. erate programming is not enough. Documenting your To illustrate this, let us mention the case of macros around their implementation is not enough. CurVe in which, at some point, we decided to sup- The casual user is not interested in the brute list of port the splitbib package. In order to do so, we commands, nor in the internals of your package. The needed to override some parts of splitbib’s macro casual user wants an overview of the package, what it \NMSB@writeentry. This macro was originally 203 is for, what it can do, what it can’t, probably a quick lines long. After dead branch removal, that is, after start guide describing the entry points and the de- cutting out pieces of code that we knew would never fault behavior, with examples. Only then, when the be executed in the context of CurVe, we ended up major concepts are understood, you may delve into with 156 lines that needed to be imported into CurVe, complexity and start talking about customization, only to modify 5 of them. Our modifications conse- additional but less important features, and so on. quently involve only 3% of the code that needed to A good user manual will sacrifice sufficiency be imported. One can easily imagine how bad this is to the benefit of gradualness and redundancy. You in terms of maintainability. We need to keep track shouldn’t be afraid of lying by omission to the readers. of potential modifications on 203 lines of splitbib It is for their own good. They don’t want to be just to make sure our 5 keep functioning correctly. overwhelmed by information. A typical hint that you are reading a bad manual is when the documentation 4 Level 3: Behavior starts with the full list of package options. There In the previous section, we claimed to be more con- is no point in introducing an option dealing with cerned with how to implement particular features, a concept that the reader does not understand yet rather than the features themselves. In this section, (that would be a reference manual). Another hint is we focus on features through the lens of behavior. when a manual starts referring to another package What we are interested in is the impact of your pack- (that it happens to use internally) and assumes that age features on the people that may interact with it. the reader knows everything about it already. The end user shouldn’t have to read two or three other manuals to understand yours, especially if in the end, 4.1 Rule #1: Be user-friendly they will never use those other packages directly. The first category of people who will interact with Why, as we said earlier, can it be rewarding to your package is its end users. Hopefully, you belong write a good manual? Because writing documenta- to this category as well. There is, however, one major tion is in fact a feedback loop. The difficult thing, difference between you and other users: you know the again, is to put yourself in the position of someone package much better than they do, since you wrote it. who knows nothing about the things you are going Being user-friendly means doing everything possible to talk about, and ask yourself: “what do I need to make your package easy to use. This can mean to say first?” If you can do that, you will discover many different things, but two important aspects are that many times, the answers to that question reveal documentation and backward compatibility. design flaws in your package, its design or its APIs. Things that a casual user would want to do but can’t, 4.1.1 Documentation things that should be simple to do but aren’t, de- Nowadays, the vast majority of LATEX packages comes fault behavior that shouldn’t be by default, concepts with documentation. The combination of doc, ltxdoc that are not apparent enough, not distinct enough, and docstrip, by allowing for literate programming, names that are not sufficiently self-explanatory. Etc. has greatly helped the community in this respect. other words, writing or improving the quality of your Nevertheless, there remains a huge difference between manual often helps you improve the quality of your documentation and good documentation. code, and vice-versa. The difficulty in writing good documentation is to put yourself in the position of the casual user — 4.1.2 Backward compatibility which you are not because you know the package Documentation is an important feature. Backward so well already. Thinking from a user perspective is compatibility is another. Users can get very frus- probably the most difficult thing to do, but it can trated when a package breaks their documents from also be a very rewarding experience (we will get back one version to another, or more generally, when a to this later). document doesn’t compile anymore after a couple
Towards LATEX coding standards 322 TUGboat, Volume 32 (2011), No. 3
of years. This was in fact a concern that Donald \ExecuteOptionsX[my]
Didier Verna TUGboat, Volume 32 (2011), No. 3 323
backward compatibility less of a burden, consider one including concerns that we have described already, of the most frequently newbie-asked questions about such as modularity. In this section we would like LATEX: how do I make a numbered section which to emphasize some higher level aspects, notably the does not appear in the table of contents (TOC)? The general problem of code organization. In our experi- general answer is that you can’t with the standard ence, we find that organizing code in a bottom-up interface. You need to reprogram a sectioning macro and feature-oriented way works best. with explicit manipulation of the section counter, etc. We know that \section creates a numbered 4.2.1 From bottom to top section which goes in the TOC. We also know that Organizing code in a bottom-up fashion means that \section* creates an unnumbered section that does you build layers on top of layers and you organize not go in the TOC. Finally, the optional argument those layers sequentially in the source file(s). The to \section allows you to provide a TOC-specific advantage in being bottom-up is that when people (shorter) title. So it turns out that there’s no stan- (including yourself) read the code, they can rely on dard way to extend the functionality in a backward- the fact that what they see only depends on what compatible way, without cluttering the syntax (either has been defined above (previously). Learning seems by creating a third macro, or by providing a new set to be essentially an incremental process. Reading of options in parentheses for instance). In fact, two is essentially a sequential process. Being bottom-up macros for one sectioning command is already one helps to conform to these cognitive aspects. too many. The bottom-up approach is sometimes confused Now imagine that key-value interfaces existed with the design of a hierarchical model in which one when \section was designed. We could have ended tries to establish nested layers (or rings) of function- up with something like this: ality. These are different things. For example, not all % Number and TOC: problems can be modeled in a hierarchical way and \section{Title} trying to impose hierarchy leads to a broken design. Sometimes, it is better to be modular than hierar- % TOC-specific title: chical. Some concepts are simply orthogonal to each \section[toctitle={Shorter Title}]{Title} other, without one being on top of the other. The bottom-up approach allows for that. When you have % Unnumbered and not in the TOC: two orthogonal features to implement, you can just \section[numbered=false]{Title} write them down one after the other, in no particular Obviously here, we intentionally reproduce the order. The only rule is that one feature depends only same design mistake as in the original version: as- on the preceding, or more precisely, a subset of the suming that unnumbered also implicitly means no preceding. TOC is suboptimal behavior. But in spite of this de- As a code organization principle, the bottom-up ficiency, when somebody wanted a numbered section approach will also inevitably suffer from a few ex- not going in the TOC, we could have added a new ceptions. Any reasonably complex program provides option without breaking anything: intermixed functionality that cannot be implemented \section[toc=false]{Title} in a bottom-up fashion. Macro inter-dependency (for What’s more, we could also handle the opposite instance, mutual recursion) is one such case. Another request for free: an unnumbered section still going typical scenario is that of polymorphic macros (cf. in the TOC: figure 6 on page 320): you may need to use a poly- \section[numbered=false,toc=true]{Title} morphic macro at a time when it hasn’t been \let to its actual implementation yet. Those exceptions 4.2 Rule #2: Be hacker-friendly are unavoidable and are not to be feared. A short The second category of people who will interact with comment in the code can help the reader navigate your package is its “hackers”, that is, the people that through those detours. may need to examine your code or even modify it for intercession purposes. Of course, you are the 4.2.2 Feature-oriented organization first person to be in this category. Being hacker- In terms of code organization, the second principle friendly means doing everything possible to make to which we try to conform is arranging the code by your package easy to read, understand and modify. feature instead of by implementation. This means Note that as the first person in this category, you that we have a tendency to think in terms of “what it end up doing yourself a favor in the first place. Be- does” rather than “how it does it” when we organize ing hacker-friendly can mean many different things, code sections in source files. In our case, this is a
Towards LATEX coding standards 324 TUGboat, Volume 32 (2011), No. 3
relatively recent change of perspective which, again, comes from the idea of putting oneself in the “hacker” \DeclareOption{english}{% position. When people need to look at your code, \def\@currlang{english}} they are most of the time interested in one particular \DeclareOption{french}{% feature that they want to imitate, extend, modify \def\@currlang{french}} or adapt for whatever reason. In such a situation, %% ... acquiring an understanding of the feature’s inner After that, using the appropriate “continued” string workings is easier when all the code related to that is a matter of calling feature is localized at the same place in the source. \csname continued\@currlang name\endcsname To illustrate this, we will intentionally take an This new form of code organization has several ad- example which may be controversial: the case of vantages. First, all the code related to one specific internationalization. The C rV class has several fea- u e feature is now localized in a single place. Next, it con- tures which need to be internationalized: rubrics forms better to the bottom-up approach (no forward need a “continued” string in case they extend across reference to a multi-lingual string macro is needed). several pages, bibliographic sections need a “List of Finally, and perhaps unintentionally, we have im- Publications” title, etc. In C rV 1, the code is al- u e proved the flexibility of our package: by implement- ready organized by feature, except for multi-lingual ing a macro such as \@currlang, we can provide strings which are all grouped at the end, like this: the user with a means to dynamically change the %% Implement rubrics current language right in the middle of a document, %% ... something that was not possible before (language processing was done when the package was loaded). %% Implement bibliography Earlier, we said that this example was taken %% ... intentionally because of its controversial nature. In- deed, one could object here that if someone wants \DeclareOption{english}{% \continuedname{continued} to modify the multi-lingual strings, or say, support a \listpubname{List of Publications}} new language, the first version is better because all \DeclareOption{french}{% internationalization macros are localized in a single \continuedname{suite} place. It is true that if you consider internation- \listpubname{Liste des Publications}} alization as a feature, then our very own principle %% ... would dictate to use the first version. This is simply These days, we find this unsatisfactory because the a demonstration that in general, there is no single code for each feature is scattered in several places. classification scheme that can work for all purposes. For instance, the \continuedname macro really be- However, we think that this argument is not really longs to the rubrics section and hence should not ap- pertinent. If you would indeed want to modify all pear at the end of the file. This kind of organization the multi-lingual strings, you would open the source is indeed implementation-oriented instead of feature- file in Emacs and use the occur library to get all oriented: we grouped all multi-lingual strings at the lines matching the regular expression end because in terms of implementation, the idea is ^\\newcommand\*\\.+name{ to define a bunch of \
Didier Verna TUGboat, Volume 32 (2011), No. 3 325
\@ifpackageloaded allows you to detect when • Next, handle compatibility problems with pack- a package has been used or required, and possibly ages, one at a time, and only locally: use pre- take counter-measures. However, this is only a cu- and post-hooks exclusively to do so. rative way of doing things: it only lets you provide • Remember that hook code is only potential: post-loading (a posteriori) code. What if you need none of it will be executed if the correspond- to take precautionary measures instead? ing package is not loaded. \AtBeginDocument allows one to massively de- • Also, note that getting information on pack- fer code execution until the beginning of a document, age loading order is now trivial if you use that is, after every package has been loaded. This \@ifpackageloaded in a pre-hook. is obviously a very gross granularity. For example, it doesn’t provide any information on the order in • Avoid using \AtBeginDocument for intercession, which the packages have been loaded, something that unless absolutely necessary; for instance, if you might be needed even for post-preamble code. need to take a counter-measure against a pack- Consider for example the following scenario: age that already uses it. Again, in such a case, calling \AtBeginDocument in a post-hook will • Style S calls \AtBeginDocument{\things} allow you to plug in the relevant code at exactly • Class C loads style S the right position in the \@begindocumenthook chain. And ask yourself the following question: how does class C intercede on \things? There is no simple 4.3.3 Bibliography management in CurVe way to sort this out with the standard LAT X tools. E To provide a concrete example of these ideas, let us demonstrate how recent versions of CurVe handle com- 4.3.2 filehook patibility with various bibliography-related packages. Like probably almost every package developer, we A summarized version is given in figure 8 on the have fought against these problems for years with following page. Roughly speaking, what this code intricate and obfuscated logic to fix inter-package does is: compatibility. We think however that the very recent • install the default, CurVe-specific behavior first, appearance of Martin Scharrer’s filehook package • step back if bibentry is loaded, is (should be) a crucial component in cleaning up • merge with multibib, the current intercession mess. • step back before splitbib and re-merge after- The filehook package provides pre- and post- wards, loading hooks to files that you input in every pos- • render hyperref inoperative. sible way (\include’d files, packages, even class Knowing where we came from, that is, how this files). Thanks to that, one can now handle inter- logic was done before filehook, it is amazing how cession in a context-free way, which is much better readable, clear, concise, and in fact simple, this new than what was possible before. For example, you implementation is. We cannot be sure how striking can take both a priori and a posteriori counter- this will be for the unacquainted reader, but in case measures against any package, without even knowing it is not, you are invited, as an exercise, to try an for sure if the package is going to be loaded at all. implement this only with the standard LAT X macros This notably includes the possibility of saving and E (hint: it is practically impossible). restoring functionality, much like what OpenGL does Earlier, we claimed that filehook would allow with its PushMatrix / PopMatrix or PushAttrib / us to program in a context-free way. Let us explain PopAttrib functions (although OpenGL uses real now what we meant by that. First of all, note that stacks for this). because we use hooks exclusively to plug our inter- Eventually, the existence of filehook allowed cession code, the five special cases could have been us to come up with a particular design pattern for implemented in any order in the C rV source file. intercession management that can be summarized as u e We can move the five blocks around without modify- follows. So far, this pattern works (for us) surpris- ing the semantics of the program. This is what we ingly well. mean by being “context-free”: the current dynamic • First of all, start by writing your code as if state of the program has no effect on the code we there were no intercession problem. In other put in hooks. Another instance of context freedom words, simply implement the default behavior is in the specific case of hyperref. The important as usual, assuming that no other package would thing to notice here is that we save (and restore) be loaded. whatever state we had just before loading hyperref.
Towards LATEX coding standards 326 TUGboat, Volume 32 (2011), No. 3
%% Step 1: implement the default bibliographic behavior %% ...
%% Backup LaTeX’s original macros and replace them by our own: \let\@curveltx@lbibitem\@lbibitem \def\@curve@lbibitem[#1]#2{...} \let\@lbibitem\@curve@lbibitem %% ... do the same for \@bibitem, \bibitem etc.
%% Step 2: special cases
%% Bibentry. Restore standard definitions because bibentry just inlines %% bibliographic contents. \AtBeginOfPackageFile{bibentry}{ \let\@lbibitem\@curveltx@lbibitem ...}
%% Multibbl. Merge its definition of \bibliography with ours. \AtEndOfPackageFile{multibbl}{ \def\bibliography##1##2##3{...}}
%% Splitbib. %% Before: restore standard definitions because ours are only used as part of %% the \endthebibliography redefinition. \AtBeginOfPackageFile{splitbib}{ \let\@lbibitem\@curveltx@lbibitem ...} %% After: Modify \NMSB@writeentry and re-modify \endthebibliography back. \AtEndOfPackageFile{splitbib}{ \def\NMSB@writeentry##1##2##3##4##5,{...}% \def\endthebibliography{...}}
%% Hyperref. Currently, we don’t want hyperref to modify our bibliographic %% code, so we save and restore whatever bibliographic state we had before %% hyperref was loaded. \AtBeginOfPackageFile{hyperref}{ \let\@curveprevious@lbibitem\@lbibitem ...} \AtEndOfPackageFile{hyperref}{ \let\@lbibitem\@curveprevious@lbibitem ...}
Figure 8: Intercession management
In other words, here again we don’t need to know our human behavior may affect the LATEX world and in exact context (the specific definition for the macros particular the development of packages. We only involved). We just need to save and restore it. And provide two simple rules, and a rather unfortunate, again, it is impossible to do that without the abil- but quite illustrative story. ity to hook code before and after package loading — We mentioned in the introduction the anti-social which filehook now provides. development syndrome that LATEX seems to suffer from. In our opinion, this behavior is what leads to wheel-reinvention (cf. section 3.1 on page 318) 5 Level 4: Social and hence redundancy (for instance, the existence of This section, shorter than the others, addresses a final half a dozen packages for key-value interfaces). In level (or rather, a meta-level) in coding standards: an ideal world, the situation could be improved by the social level. Here, we are interested in how the following the two simple rules described below.
Didier Verna TUGboat, Volume 32 (2011), No. 3 327
5.1 Rule #1: Be proactive tains the name of the file currently being processed A The first rule of thumb is to permanently try to trig- by LTEX. Martin was inquiring about a potential ger collaboration. Package development frequently cross-compatibility with FiNK, one of our own pack- comes from the fact that you are missing a particular ages, which does exactly the same thing. functionality. However, there is little chance that We answered politely with the requested infor- you are the first person to miss the functionality in mation and continued the email conversation for a question. Therefore, the first thing to do is to look little while, not without a wee bit of frustration how- for an existing solution instead of starting your own. ever. Why yet another package for this? Wasn’t By the way, we know that it is fun to start one’s FiNK good enough? Couldn’t its functionality have own solution. We have done that before, but it is been extended rather than duplicated? nothing to be proud of! Interestingly enough, we were recently sorting Once you find an already existing solution (and out some old mail when we dug up a message from you will, most of the time), it will probably not be an this very same Martin Scharrer, providing a patch exact match. You will feel the need for implementing against FiNK in order to ground it onto filehook. a variant or an extension of some kind. Here again, This message was one year and thirty eight weeks old. don’t take this as an excuse to start your own work, Of course, we had completely forgotten all about it. and don’t keep your work for yourself either. Try to In terms of time frame, one year and thirty eight be proactive and trigger collaboration: contact the weeks is way beyond “reasonable”. So much for being original author and see if your ideas or your code reactive, lesson learned, the hard way. . . could be merged in some way with the upstream 6 Conclusion branch. This is the first key to avoid redundancy. In this paper, we addressed the notion of LATEX cod- 5.2 Rule #2: Be reactive ing standards. We started by analyzing the reasons Of course, this can only work if there is a response why no such thing seems to exist as of yet. In short, from the other side. And this is the second rule of the lack of coding standards for LATEX can be justi- thumb: if collaboration is proposed, accept it. Main- fied by a mostly anti-social development syndrome, taining a package should be regarded as a certain a not so pressing need for them in the view of the responsibility towards its users. People frequently es- developers and the lack of help and support from the cape from their maintenance responsibility by hiding usual text editors. We however demonstrated that behind the free software banner (free as in freedom having a set of coding standards would be extremely and/or as in beer). This is of course legitimate but beneficial to the community. First, they would help also abused to the point of leading to the anti-social make the most of a programming language that is syndrome we have been discussing. far less structured than the more casual ones. Next, Being reactive means reviewing and accepting they would also help in terms of code homogeneity patches from other people in a reasonable time frame and readability, both key components in collabora- (for some definition of “reasonable”). It also means tion. This is especially important in LATEX because listening to other people’s suggestions and implement- even if intentional collaboration is not so widespread, ing them within the same reasonable time frame. We there is a very frequent form of forced collaboration, understand that this is not always possible, but when which is intercession (inter-package compatibility and you feel that there is some kind of pressure on you, conflict management). there is also an alternative: trust people and open We then reported on our own development expe- the development. Use a version control system (VC) rience and proposed a set of rules and design patterns of some kind. Put your code on github or a similar that have helped improve our own code over the years. place and let people hack on it. The advantage to Those rules were organized in four different abstrac- using a VC is that it is always possible to revert to tion levels: layout (formatting and naming policies), an earlier state in the history of the package. design (modularity and other programming para- digms), behavior (interfaces and intercession man- 5.2.1 FiNK and currfile agement) and finally the meta-level (social behavior). We realize these considerations may be somewhat ide- We don’t expect that everyone would agree to alistic. In order to illustrate why they are important every one of these rules, as we know that a coding anyways let us tell a short story. style is above all a matter of personal taste. In Sometime in 2010, we were contacted by Martin fact, a coding style is important, but it is even more Scharrer, the author of filehook, about another important to stick to it, that is, to stay coherent with package of his named currfile. This package main- yourself. Developing a coding style is also a matter of
Towards LATEX coding standards 328 TUGboat, Volume 32 (2011), No. 3
keeping the problem in mind permanently, not unlike Patterns for Resource Management, volume 3. a daemonized process running in the background of Wiley, 2004. one’s head. Every time you write a line of code, you [10] Patty Maes. Concepts and experiments in need to ask yourself, “is this the proper way to do computational reflection. In OOPSLA. ACM, it?” This also means that a coding style may be December 1987. a moving target, at least partially. It will evolve [11] Frank Mittelbach. Reflections on the along with the quality of your code. Finally, one history of the LAT X Project Public License should remember that there can be no rule without E (LPPL) — A software license for LAT X and exceptions. Knowing when to escape from your style E more. TUGboat, 32(1):83–94, 2011. http: for the greater good is as important as conforming //tug.org/TUGboat/tb32-1/tb100mitt.pdf. to it. The ideas, rules and design patterns proposed [12] Frank Mittelbach, Michel Goossens, Johannes in this article are those that work best for us, but Braams, David Carlisle, and Chris Rowley. our hope is that they will also help you too. Many The LATEX Companion, second edition. other ideas have not been tackled in this paper, both Addison Wesley, 2004. at the level of the document author and at the level [13] Douglas C. Schmidt, Michael Stal, of the package developer. Much more could be said Hans Rohnert, and Frank Buschmann. on the matter, and if there is enough interest in the Pattern-Oriented Software Architecture: community, maybe it is time for an “Elements of Patterns for Concurrent and Networked LATEX Programming Style” book which remains to Objects, volume 2. Wiley, 2000. be written. Perhaps this article could serve as a basis [14] Brian C. Smith. Reflection and semantics for such a book, and we would definitely be willing in Lisp. In Symposium on Principles of to work on such a project. Programming Languages, pages 23–35. References ACM, 1984. [15] Richard M. Stallman. The GNU coding [1] AUC-T X. http://www.gnu.org/s/auctex. E standards. http://www.gnu.org/prep/ [2] The comprehensive TEX archive network. standards. http://www.ctan.org. [16] William Strunk Jr. and E.B. White. The [3] The XEmacs text editor. Elements of Style. W.P. Humphrey, 1918. http://www.xemacs.org. [17] Didier Verna. The CurVe class. http: [4] F. Buschmann, R. Meunier, H. Rohnert, //www.lrde.epita.fr/~didier/software/ P. Sommerlad, and M. Stal. Pattern-Oriented latex.php#curve. Software Architecture, volume 1. Wiley, 1996. [18] Didier Verna. The FiXme style. http: [5] Frank Buschmann, Kevlin Henney, and //www.lrde.epita.fr/~didier/software/ Douglas C. Schmidt. Pattern-Oriented latex.php#fixme. Software Architecture: A Pattern Language [19] Didier Verna. Classes, styles, conflicts: for Distributed Computing, volume 4. The biological realm of LAT X. TUGboat, Wiley, 2007. E 31(2):162–172, 2010. http://tug.org/ [6] Frank Buschmann, Kevlin Henney, and TUGboat/tb31-2/tb98verna.pdf. Douglas C. Schmidt. Pattern-Oriented Software Architecture: A Pattern Language [20] Joseph Wright and Christian Feuers¨anger. for Distributed Computing, volume 5. Implementing key–value input: An Wiley, 2007. introduction. TUGboat, 30(1):110–122, 2009. http://tug.org/TUGboat/tb30-1/ [7] E. Gamma, R. Helm, R. Johnson, and tb94wright-keyval.pdf. J. Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley, 1994. Didier Verna EPITA / LRDE [8] B.W. Kernighan and P.J. Plauger. The 14-16 rue Voltaire Elements of Programming Style. 94276 Le Kremlin-BicˆetreCedex McGraw-Hill, 1974. France [9] Michael Kircher and Prashant Jain. didier (at) lrde dot epita dot fr Pattern-Oriented Software Architecture: http://www.lrde.epita.fr/~didier
Didier Verna