Using LaTeX3 expl3 and NewDocumentCommand for Robust Command Definitions

The problem is silent misuse, not missing features

In a modular LaTeX project with several authors, a command defined with \newcommand is easy to misuse. \newcommand\unit[2]{...} expects two arguments, but the author can swap them, omit the second, or add stray brackets that are silently absorbed. The mistake only appears in the output, not as a clear compile error.

Why explicit signatures improve maintainability

expl3 is the LaTeX3 programming layer now part of the LaTeX kernel. It offers a stable naming convention, data types and programming tools that work across pdfLaTeX, XeLaTeX and LuaLaTeX. \NewDocumentCommand, integrated from the xparse interface, lets you declare a command signature with argument types such as m (mandatory), o (optional), O{default} (optional with default), * (starred variant) and +m (long argument). The parser enforces the signature, giving a clear error when the call does not match.

Because argument handling is centralized in the definition, refactoring is safer. Changing the unit format or citation style happens in one place, not in dozens of calls spread across subfiles or standalone chapters.

Worked example: a chemical formula wrapper

The following definition can go in the preamble or a shared .sty file. It uses siunitx for formatting but the idea applies to any package.

% preamble
\NewDocumentCommand\chem{m o}{%
  \IfNoValueTF{#2}{%
    \mathrm{#1}%   % just the formula
  }{%
    \mathrm{#1}_{#2}%   % formula with subscript
  }%
}

Signature meaning: m is the mandatory formula (e.g., CO2), o is an optional subscript. A call \chem{CO2} yields \mathrm{CO2}. A call \chem{CO2}{3} yields \mathrm{CO2}_{3}. If you forget the mandatory argument, the parser reports a missing argument rather than producing silent output.

To test, create a minimal document with \documentclass{article}, load siunitx if you wish, place the definition in the preamble, and compile with pdfLaTeX or LuaLaTeX. Intentionally omit the mandatory argument, e.g., \chem{}, and check the log for a message like \"You haven't specified a mandatory argument\". Also verify that \NewDocumentCommand is not undefined; if it is, add \usepackage{xparse} as a fallback and plan to upgrade to a TeX Live 2020+ base image.

Trade‑offs and limits

The upfront definition is longer than a simple \newcommand, and authors need to learn expl3 naming conventions. Very old TeX distributions (pre‑2020) may lack kernel integration and require \usepackage{xparse} explicitly. Complex argument types like +m or verbatim‑like arguments can interact poorly with fragile commands inside moving arguments such as section titles unless protected. Some legacy packages assume traditional \newcommand definitions and may clash with robust commands defined via \NewDocumentCommand. Performance impact is negligible for typical documents, but very large numbers of parsed arguments can increase compile time. Follow expl3 naming conventions to avoid macro collisions.

Actionable closing

Pick one frequently misused command in a shared style file, replace its \newcommand definition with a \NewDocumentCommand that declares an explicit signature. Add a comment above the definition documenting the signature. Include a minimal test file that calls the command with correct, missing, and starred forms to confirm the parser rejects bad calls. Explicit argument parsing does not replace good documentation, but it makes the contract visible and enforced, turning silent drift into maintainable LaTeX.