Macros

Use macros sparingly. Don't include a kitchen-sink full of macros in an article length document

Some authors have, over the years, acquired a large macro collection, and made it a habit to include this collection (their "kitchen-sink") in every paper they write. I strongly recommend against this practice. An excessively long list of macros makes a document hard to maintain and increases the chances of conflicts between macros, or of one macro inadvertently overriding another (or a predefined command). In addition, papers with extensive lists of macros, especially those with complex custom macros that override the default behavior of Latex, are much harder to process at the publisher's end, as any custom macros will likely have to be removed, or modified, in order to make the paper conform to the journal style. The extensive editing at the publisher's end that this requires in turn increases the chances of inadvertently introducing errors.

For these reasons, it is best to only include macros that are actually used in the document. I usually start with a blank slate and add macros as needed for frequently occurring constructs. I rarely need more than two or three dozen macros for an article length document, and almost all of those are harmless "abbreviation type" macros. For a thesis and other book-length documents a more extensive macro collection, and more complex macros (e.g., macros defining new environments), may be appropriate. However, don't fall into the habit of including your thesis macro set in every paper you write; trim it down to what you actually need in the paper.

Keep it simple. Avoid complex macros, and use those only if you really know what you are doing

The more complex a macro is, the greater the chance that something goes wrong, and the more difficult it will be to diagnose and fix any problems. With Latex (in contrast to plain TeX), there is rarely a need for introducing complex macros. Latex has built-in constructs for nearly everything one would want in a typical mathematical paper. In addition, there are numerous add-on packages available that provide additional sets of predefined macros and which can be included with a simple \usepackage{...} instruction.

Define your own macros, don't copy someone else's

Don't blindly copy someone else's macros, or use someone else's paper as template, with all the macros preserved. Chances are that many of these macros are not needed for your own paper, so you'll end up with an unnecessarily long list of macros, with all the problems that this entails. Also, since most authors' TeX skills are less than perfect, you may acquire poorly constructed macros and bad coding practices. Finally, if you copy complex macros that someone else has written, but don't have a real understanding how they work, you'll be unable to modify or adapt these to a particular situation, and if something goes wrong with the macro, you'll have a hard time tracking down the error. If a macro is over your head, don't use it; find a simpler solution (there almost always is).

Put all macros in a single place near the top of the document, group macros by function, and put each macro on a separate line

Don't scatter macros throughout the document. If midway through editing a document you find that could use another macro, insert it in the preamble at the top of the document. Having all macros in a single place makes it easier to maintain these macros, and to detect any problems or inconsistencies.

Similarly, grouping similar macros (e.g., all theorem declarations (\newtheorem{...}), followed by math font macros (\mathbb{N}), followed by operator definitions (\operatorname{...}), etc.), and by putting each macro on a line by itself makes it easier to spot a macro, and the file more maintainable.

Define macros with \newcommand. Use \renewcommand sparingly if at all, and avoid \def completely unless you really know what you are doing

"\newcommand" is the Latex way of defining macros; "\def" is the old, plain TeX style, definition. Using "\newcommand" is far preferable, since \newcommand checks against existing definitions and generates an error message if a macro name is in use. By contrast, "\def" happily overwrites any existing definition; this may cause unexpected errors that are often hard to track down.

If a "\newcommand" definition generates an error message because of a conflict with an existing macro, don't try to get rid of the error message by changing "\newcommand" to "\def". There is a good reason why Latex produces an error message in the first place, and if you choose to ignore the message, you risk running into problems associated with overriding existing definitions. A slightly safer approach is to replace "\newcommand" by "\renewcommand", but that, too, is fraught with some risks. The best way is to eliminate conflicts by changing the name of the macro to one that is not already defined.

Avoid one letter macros

Many one letter sequences have predefined meanings and thus cause conflicts if you try to use them for your own macros. Most of these one-letter macros are part of the TeX core, and usually not documented in Latex books. Thus, if a macro isn't listed in the index of a Latex book, it doesn't mean that it is not in use. To be certain that a macro isn't in use, you would have to check the original Knuth TeXbook, in addition to a comprehensive Latex reference.

You can largely avoid running into such problems by using at least two letters for a macro name. While there exist a few (non-obvious) two letter sequences that have predefined meanings (e.g., \aa), those are quite rare and the vast majority of two letter sequences are available as macro names. For example, to define \mathbf{v}, use \vv, or \bv (for "bold v"), rather than \v. The latter, \v, is predefined, whereas both \vv and \bv are available.

Avoid defining macros/abbreviations for \begin{...} or \end{...}

While TeXnically there is nothing wrong with defining, for example, "\be" and "\ee" as abbreviations for "\begin{equation}" and "\end{equation}", I try to avoid such abbreviations, for a number of reasons:

Avoid defining macros for ordinary English words and phrases

I recommend against defining macros as abbreviations for ordinary words and phrases, e.g, "\rh" for "Riemann Hypothesis", "\ae" for "almost everywhere", "\rv" for "random variable", etc. While, from a TeXnical point of view, such abbreviation macros cause no problems or conflicts, I try to avoid these for a number of reasons:

Some common examples of macro definitions

Here are some common situations where macros are appropriate:

Back to the LaTeX Tips Page

Last modified: Tue 23 Aug 2011 05:47:48 PM CDT A.J. Hildebrand