Debian Codegraph @

texmf-dist/doc/latex/l3kernel/l3styleguide.tex

raw
1 \iffalse meta-comment
2
3 File: l3styleguide.tex
4
5 Copyright (C) 2011,2012,2014-2026 The LaTeX Project
6
7 It may be distributed and/or modified under the conditions of the
8 LaTeX Project Public License (LPPL), either version 1.3c of this
9 license or (at your option) any later version. The latest version
10 of this license is in the file
11
12 https://www.latex-project.org/lppl.txt
13
14 This file is part of the "l3kernel bundle" (The Work in LPPL)
15 and all files in that bundle must be distributed together.
16
17 The released version of this bundle is available from CTAN.
18
19 \fi
20
21 \documentclass{l3doc}
22
23
24 \title{%
25 The \LaTeX3 kernel: style guide for code authors%
26 }
27 \author{%
28 The \LaTeX{} Project\thanks
29 {%
30 E-mail:
31 \href{mailto:[email protected]}%
32 {[email protected]}%
33 }%
34 }
35 \date{Released 2026-05-15}
36
37 \begin{document}
38
39 \maketitle
40
41 \tableofcontents
42
43 \section{Introduction}
44
45 This document is intended as a style guide for authors of code and
46 documentation for the \LaTeX3 kernel. It covers both aspects of coding
47 style and the formatting of the sources. The aim of providing these
48 guidelines is help ensure consistency of the code and sources from
49 different authors. Experience suggests that in the long-term this helps
50 with maintenance. There will of course be places where there are
51 exceptions to these guidelines: common sense should always be
52 applied!
53
54 \section{Documentation style}
55
56 \LaTeX3 source and documentation should be written using the document
57 class \cls{l3doc} in \file{dtx} format. This class provides a number
58 of logical mark up elements, which should be used where possible.
59 In the main, this is standard \LaTeX{} practice, but there are a
60 few points to highlight:
61 \begin{itemize}
62 \item
63 Where possible, use \cs{cs} to mark up control sequences
64 rather than using a verbatim environment.
65 \item
66 Arguments which are given in braces should be marked using
67 \cs{Arg} when code-level functions are discussed, but using
68 \cs{marg} for document functions.
69 \item
70 The names \TeX{}, \LaTeX{}, \emph{etc}.\ use the normal logical mark
71 up followed by an empty group (|{}|), with the exception of |\LaTeX3|,
72 where the number should follow directly.
73 \item
74 Where in line verbatim text is used, it should be marked up
75 using the \verb=|...|= construct (i.e., vertical bars delimit
76 the verbatim text).
77 \item In line quotes should be marked up using the \cs{enquote}
78 function.
79 \item
80 Where numbers in the source have a mathematical meaning,
81 they should be included in math mode. Such in-line math mode
82 material should be marked up using |$...$| and \emph{not}
83 |\(...\)|.
84 \end{itemize}
85
86 Line length in the source files should be under $80$
87 characters where possible, as this helps keep everything on the screen
88 when editing files. In the \file{dtx} format, documentation lines start
89 with a \texttt{\%}, which is usually followed by a space to leave a
90 \enquote{comment margin} at the start of each line.
91
92 As with code indenting (see later), nested environments and arguments
93 should be indented by (at least) two spaces to make the nature of the nesting
94 clear. Thus for example a typical arrangement for the \env{function}
95 environment might be
96 \begin{verbatim*}
97 \begin{function}{\seq_gclear:N, \seq_gclear:c}
98 \begin{syntax}
99 \cs{seq_gclear:N} \meta{sequence}
100 \end{syntax}
101 Clears all entries from the \meta{sequence} globally.
102 \end{function}
103 \end{verbatim*}
104 The \enquote{outer} \verb*|% \begin{function}| should have the customary
105 space after the |%| character at the start of the line.
106
107 In general, a single \env{function} or \env{macro} environment should be
108 used for a group of closely-related functions, for example argument
109 specification variants. In such cases, a comma-separated list should be
110 used, as shown in the preceding example.
111
112 \section{Format of the code itself}
113
114 The requirement for fewer than $80$ characters per line applies to the code
115 itself as well as the surrounding documentation. A number of the general
116 style principles for \LaTeX3 code apply: these are described in the following
117 paragraph and an example is then given.
118
119 With the exception of simple runs of parameter (|{#1}|, |#1#2|,
120 etc.), everything should be divided up using spaces to make the code
121 more readable. In general, these will be single spaces, but in some
122 places it makes more sense to align parts of the code to emphasize
123 similarity. (Tabs should not be used for introducing white space.)
124
125 Each conceptually-separate step in a function should be on a separate
126 line, to make the meaning clearer. Hence the \texttt{false} branch
127 in the example uses two lines for the two auxiliary function uses.
128
129 Within the definition, a two-space indent should be used to show each
130 \enquote{level} of code. Thus in the example \cs{tl_if_empty:nTF} is
131 indented by two spaces, but the two branches are indented by four
132 spaces. Within the \texttt{false} branch, the need for multiple lines
133 means that an additional two-space indent should be used to show that
134 these lines are all part of the brace group.
135
136 The result of these lay-out conventions is code which in general
137 looks like the example:
138 \begin{verbatim*}
139 \cs_new:Npn \module_foo:nn #1#2
140 {
141 \tl_if_empty:nTF {#1}
142 { \module_foo_aux:n { X #2 } }
143 {
144 \module_foo_aux:nn {#1} {#2}
145 \module_foo_aux:n { #1 #2 }
146 }
147 }
148 \end{verbatim*}
149
150 \section{Code conventions}
151
152 All code-level functions should be \enquote{long} if they accept any
153 arguments, even if it seems \enquote{very unlikely} that a \cs{par} token
154 will be passed. Thus \cs{cs_new_nopar:Npn} and so forth should only be used
155 to create interfaces at the document level (where trapping \cs{par} tokens
156 may be appropriate) or where comparison to other code known not to be
157 \enquote{long} is required (\emph{e.g.}~when working with mixed
158 \LaTeXe{}/\pkg{expl3} situations).
159
160 The expandability of each function should be well-defined. Functions which
161 cannot be fully expanded must be \texttt{protected}. This means that expandable
162 functions must themselves only contain expandable material. Functions which
163 use any non-expandable material must be defined using \cs{cs_new_protected:Npn}
164 or similar.
165
166 When using \cs{cs_generate_variant:Nn}, group related variants together
167 to make the pattern clearer. A common example is variants of a function
168 which has an \texttt{N}-type first argument:
169 \begin{verbatim}
170 \cs_generate_variant:Nn \foo:Nn { NV , No }
171 \cs_generate_variant:Nn \foo:Nn { c , cV , co }
172 \end{verbatim}
173
174 There may be cases where omitting braces from \texttt{o}-type arguments
175 is desirable for performance reasons. This should only be done if the
176 argument is a single token, thus for example
177 \begin{verbatim}
178 \tl_set:No \l_some_tl \l_some_other_tl
179 \end{verbatim}
180 remains clear and can be used where appropriate.
181
182 \section{Private and internal functions}
183
184 Private functions (those starting \cs{__}) should not be used between modules.
185 The only exception is where a \enquote{family} of modules share some
186 \enquote{internal} methods: this happens most obviously in the kernel itself.
187 Any internal functions or variables \emph{must} be documented in the same way
188 as public ones.
189
190 The \pkg{DocStrip} method should be used for internal functions in a module.
191 This requires a line
192 \begin{quote}
193 \ttfamily
194 \%<@@=\meta{module}>
195 \end{quote}
196 at the start of the source (\texttt{.dtx}) file, with internal functions
197 then written in the form
198 \begin{verbatim}
199 \cs_new_protected:Npn \@@_function:nn #1#2
200 ...
201 \end{verbatim}
202
203 \subsection{Access from other modules}
204
205 There may be cases where it is useful to use an internal function from
206 a third-party module (this includes cases where you are the author of both
207 but they are not part of the same \enquote{family}). In these cases, you should
208 \emph{copy} the definition of the internal function to your code: this avoids
209 relying on non-documented interfaces. At the same time, it is strongly
210 encouraged that you discuss your requirements with the author of the
211 code you need to access. The best long-term solution to these cases is for
212 new documented interfaces to be added to the parent module.
213
214 \subsection{Access to primitives}
215
216 As \pkg{expl3} is still a developing system, there are places where direct
217 access to engine primitives is required. These are all marked as
218 \enquote{do not use} in the code and so require special handling. Where a
219 programmer is sure that they need to use a primitive (for example where the
220 team have not yet covered access to an area) then a local copy of the
221 primitive should be made, for example
222 \begin{verbatim}
223 \cs_new_eq:NN \__module_message:w \tex_message:D
224 % ...
225 \cs_new_protected:Npn \__module_fancy_msg:n #1
226 { \__module_message:w { *** #1 *** } }
227 \end{verbatim}
228 This approach makes it possible for the team and others to find such
229 usage (by searching for the \texttt{:D} argument type) but avoids
230 multiple uses in general code.
231
232 At the same time, the team ask that these use cases are raised by
233 emailing us. The team are keen to collect use cases for
234 areas that have not yet been addressed and to provide new code where the
235 required interfaces become clear.
236
237 Programmers using primitives should be ready to make updates to their
238 code as the team develop additional interfaces.
239
240 \section{Auxiliary functions}
241
242 In general, the team encourages the use of descriptive names in \LaTeX3 code.
243 Thus many helper functions would have names which describe briefly what they do,
244 rather than simply indicating that they are auxiliary to some higher-level
245 function. However, there are places where one or more \texttt{aux} functions
246 are required. Where possible, these should be differentiated by signature
247 \begin{verbatim}
248 \cs_new_protected:Npn \@@_function:nn #1#2
249 {
250 ...
251 }
252 \cs_new_protected:Npn \@@_function_aux:nn #1#2
253 {
254 ...
255 }
256 \cs_new_protected:Npn \@@_function_aux:w #1#2 \q_stop
257 {
258 ...
259 }
260 \end{verbatim}
261 Where more than one auxiliary shares the same signature, the recommended naming
262 scheme is \texttt{auxi}, \texttt{auxii} and so on.
263 \begin{verbatim}
264 \cs_new_protected:Npn \@@_function_auxi:nn #1#2
265 {
266 ...
267 }
268 \cs_new_protected:Npn \@@_function_auxii:nn #1#2
269 {
270 ...
271 }
272 \end{verbatim}
273 The use of \texttt{aux_i}, \texttt{aux_ii}, etc.\ is discouraged as this
274 conflicts with the convention used by \cs{use_i:nn} and related functions.
275
276 \section{Functions with `weird' arguments}
277
278 When defining commands that do not follow the usual convention of accepting
279 arguments as single-tokens or braced-text, the \verb|w| argument specifier
280 is used to denote that the function signature cannot fully describe the syntax.
281 Two examples from the \LaTeX3 kernel are:
282 \begin{quote}
283 \verb|\use_none_delimit_by_q_stop:w| $\langle$\,\emph{text}\,$\rangle$ \verb|\q_stop|\\
284 \verb|\use_i_delimit_by_q_stop:nw| \char`\{ $\langle$\,\emph{arg}\,$\rangle$\char`}\,$\langle$\,\emph{text}\,$\rangle$ \verb|\q_stop|
285 \end{quote}
286 More complex definitions are possible if commands are to parse tokens,
287 such as the internal kernel command
288 \begin{verbatim}
289 \cs_new_protected:Npn \__clist_get:wN #1 , #2 \q_stop #3
290 { \tl_set:Nn #3 {#1} }
291 \end{verbatim}
292 When the \verb|w| specifier is being used, it is encouraged not to try
293 and complicate the rest of the signature too much---for example, it
294 would be considered poor style to have a function with a signature like
295 \verb|\foo_bar:wnw| unless there were very clear reasons of code clarity.
296 A signature such as \verb|:ww| would certainly be discouraged.
297
298 Examining the examples above, it can be seen that there are scenarios in
299 which it may make logical sense for having a signature such as \verb|:wN| or
300 \verb|:nw|, but when in doubt the recommended approach is to simply use
301 \verb|:w| as a catch-all.
302
303 \end{document}