\iffalse meta-comment File l3styleguide.tex Copyright (C) 2011,2012 The LaTeX3 Project It may be distributed and/or modified under the conditions of the LaTeX Project Public License (LPPL), either version 1.3c of this license or (at your option) any later version. The latest version of this license is in the file http://www.latex-project.org/lppl.txt This file is part of the "l3kernel bundle" (The Work in LPPL) and all files in that bundle must be distributed together. The released version of this bundle is available from CTAN. \fi \documentclass{l3doc} \usepackage{svn-multi} \svnid{$Id: l3styleguide.tex 2772 2011-09-07 15:07:41Z joseph $} \def\filedate{\svnfileyear/\svnfilemonth/\svnfileday} \title{% The \LaTeX3 kernel: style guide for code authors% \thanks {% This file describes v\svnfilerev, last revised \filedate. }% } \author{% The \LaTeX3 Project\thanks {% E-mail: \href{mailto:latex-team@latex-project.org}% {latex-team@latex-project.org}% }% } \date{Released \filedate} \begin{document} \maketitle \tableofcontents \section{Introduction} This document is intended as a style guide for authors of code and documentation for the \LaTeX3 kernel. It covers both aspects of coding style and the formatting of the sources. The aim of providing these guidelines is help ensure consistency of the code and sources from different authors. Experience suggests that in the long-term this helps with maintenance. There will of course be places where there are exceptions to these guidelines: common sense should always be applied! \section{Documentation style} \LaTeX3 source and documentation should be written using the document class \cls{l3doc} in \file{dtx} format. This class provides a number of logical mark up elements, which should be used where possible. In the main, this is standard \LaTeX{} practice, but there are a few points to highlight: \begin{itemize} \item Where possible, use \cs{cs} to mark up control sequences rather than using a verbatim environment. \item Arguments which are given in braces should be marked using \cs{Arg} when code-level functions are discussed, but using \cs{marg} for document functions. \item The names \TeX{}, \LaTeX{}, \emph{etc}.\ use the normal logical mark up followed by an empty group (|{}|), with the exception of |\LaTeX3|, where the number should follow directly. \item Where in line verbatim text is used, it should be marked up using the \verb=|...|= construct (\emph{i.e.}~vertical bars delimit the verbatim text). \item In line quotes should be marked up using the \cs{enquote} function. \item Where numbers in the source have a mathematical meaning, they should be included in math mode. Such in-line math mode material should be marked up using |$...$| and \emph{not} |\(...\)|. \end{itemize} Line length in the source files should to be under $80$ characters where possible, as this helps keep everything on the screen when editing files. In the \file{dtx} format, documentation lines start with a \texttt{\%}, which is usually followed by a space to leave a \enquote{comment margin} at the start of each line. As with code indenting (see later), nested environments and arguments should be indented by (at least) two spaces to make the nature of the nesting clear. Thus for example a typical arrangement for the \env{function} environment might be \begin{verbatim*} \begin{function}{\seq_gclear:N, \seq_gclear:c} \begin{syntax} \cs{seq_gclear:N} \meta{sequence} \end{syntax} Clears all entries from the \meta{sequence} globally. \end{function} \end{verbatim*} The \enquote{outer} \verb*|% \begin{function}| should have the customary space after the |%| character at the start of the line. In general, a single \env{function} or \env{macro} environment should be used for a group of closely-related functions, for example argument specification variants. In such cases, a comma-separated list should be used, as shown in the preceding example. \section{Format of the code itself} The requirement for less than $80$ characters per line applies to the code itself as well as the surrounding documentation. A number of the general style principals for \LaTeX3 code apply: these are described in the following paragraph and an example is then given. With the exception of simple runs of parameter (|{#1}|, |#1#2|, \emph{etc.}), everything should divided up using spaces to make the code more readable. In general, these will be single spaces, but in some places it makes more sense to align parts of the code to emphasise similarity. (Tabs should not be used for introducing white space.) Each conceptually-separate step in a function should be on a separate line, to make the meaning clearer. Hence the \texttt{false} branch in the example uses two lines for the two auxiliary function uses. Within the definition, a two-space indent should be used to show each \enquote{level} of code. Thus in the example \cs{tl_if_empty:nTF} is indented by two spaces, but the two branches are indented by four spaces. Within the \texttt{false} branch, the need for multiple lines means that an additional two-space indent should be used to show that these lines are all part of the brace group. The result of these lay-out conventions is code which will in general look like the example: \begin{verbatim*} \cs_new:Npn \module_foo:nn #1#2 { \tl_if_empty:nTF {#1} { \module_foo_aux:n { X #2 } } { \module_foo_aux:nn {#1} {#2} \module_foo_aux:n {#1#2} } } \end{verbatim*} \section{Code conventions} All code-level functions should be \enquote{long} if they accept any arguments, even if it seems \enquote{very unlikely} that a \cs{par} token will be passed. Thus \cs{cs_new_nopar:Npn} and so forth should only be used to create functions which accept no arguments at all. The expandability of each function should be well-defined. Functions which cannot be fully expanded must be \texttt{protected}. This means that expandable functions must themselves only contain expandable material. Functions which use any non-expandable material must be defined using \cs{cs_new_protected:Npn} or similar. When using \cs{cs_generate_variant:Nn}, group related variants together to make the pattern clearer. A common example is variants of a function which has an \texttt{N}-type first argument: \begin{verbatim} \cs_generate_variant:Nn \foo:Nn { NV , No } \cs_generate_variant:Nn \foo:Nn { c , cV , co } \end{verbatim} There are cases where omitting braces from \texttt{o}-type arguments is desirable for performance reasons. This should only be done if the argument is a single token, thus for example \begin{verbatim} \tl_set:No \l_some_tl \l_some_other_tl \end{verbatim} remains clear and can be used where appropriate. \section{Private and internal functions} Private functions (those starting \cs{__}) should not be used between modules. The only exception is where a \enquote{family} of modules share some \enquote{internal} methods: this happens most obviously in the kernel itself. Any internal functions or variables \emph{must} be documented in the same way as public ones. The \pkg{l3docstrip} method should be used for internal functions in a module. This requires a line \begin{quote} \ttfamily \%<@@=\meta{module}> \end{quote} at the start of the source (\texttt{.dtx}) file, with internal functions then written in the form \begin{verbatim} \cs_new_protected:Npn \@@_function:nn #1#2 ... \end{verbatim} \section{Auxiliary functions} In general, the team encourage the use of descriptive names in \LaTeX3 code. Thus many helper functions will have names which describe briefly what they do, rather than simply indicating that they are auxiliary to some higher-level function. However, there are places where one or more \texttt{aux} functions are required. Where possible, these should be differentiated by signature \begin{verbatim} \cs_new_protected:Npn \@@_function:nn #1#2 { ... } \cs_new_protected:Npn \@@_function_aux:nn #1#2 { ... } \cs_new_protected:Npn \@@_function_aux:w #1#2 \q_stop { ... } \end{verbatim} Where more than one auxiliary shares the same signature, the recommended naming scheme is \texttt{auxi}, \texttt{auxii} and so on. \begin{verbatim} \cs_new_protected:Npn \@@_function_auxi:nn #1#2 { ... } \cs_new_protected:Npn \@@_function_auxii:nn #1#2 { ... } \end{verbatim} The use of \texttt{aux_i}, \texttt{aux_ii}, \emph{etc.}\ is discouraged as this conflicts with the convention used by \cs{use_i:nn} and related functions. \end{document}