Best practices on when to create a new function vs. a command in LaTeX3

Question

After reading this article, it states:

Experienced TeX programmers will probably be worried that I’m talking about ‘functions’ and not about ‘macros’. ... The LaTeX3 programming approach allows us to treat many macros as if they were functions, but there are places where we’ll need to think about macros being expanded. Throughout the LaTeX3 documentation, programming is described in terms of functions, and so I’ll stick to that approach. Bear in mind that underlying everything is a set of macros, and that this will show up from time to time.

If "macros" are now being called "functions", but under the hood everything is still a macro, I'm wondering how we should think about when to create a macro with \NewDocumentCommand vs. creating a function such as with \cs_new:Npn.

Answer 1

TeX is a macro expansion language, so everything we can create comes down to macros. However, that is not what is important here: what we are talking about is programming layers.

A LaTeX document is constructed using commands such as \emph, \begin, \section and so on. These document commands may have take optional arguments where appropriate, and may have differing results depending on the document class. A classic example of the later is \emph: it usually means 'make italic', but in a presentation might be bold, coloured or similar. At the same time, whilst LaTeX2e uses a particular 'standard' syntax, one could define alternative document formats with different conventions at this level.

The implementation of document commands needs a code level: details of the implementation. At this level, we want clearly defined APIs in which the number of arguments is fixed and which don't depend on variable syntax in the document. For example, if I decide to change how I implement \section, I shouldn't need to worry about the optional star and optional square-bracket argument.

In LaTeX2e, there are some areas where such separation exists (\section is one), but this is not entirely systematic. In LaTeX3 work, the situation is much more clearly defined. (LaTeX2e-like) Document commands should be created using xparse (\NewDocumentCommand, etc.), and pass their argument(s) to documented code-level APIs created using expl3 (\cs_new_protected:Npn, etc.), i.e.

\NewDocumentCommand \foo { s O { } m }
  {
    \IfBooleanTF #1
      { \my_command_one:nn {#1} {#2} }
      { \my_command_two:nn {#1} {#2} }
  }
...
\cs_new_protected:Npn \my_command_one:nn #1#2
  {
    % Implementation using private \__... functions
  }