[latex3-commits] [git/LaTeX3-latex3-latex3] master: Document that variables should be declared before use (fixes #583) (b91b84f95)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/b91b84f95f1b23e5a165c00d8f202e242f33b4dc

>---------------------------------------------------------------

commit b91b84f95f1b23e5a165c00d8f202e242f33b4dc
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Jan 8 09:48:46 2020 +0000

    Document that variables should be declared before use (fixes #583)


>---------------------------------------------------------------

b91b84f95f1b23e5a165c00d8f202e242f33b4dc
 l3kernel/CHANGELOG.md |  1 +
 l3kernel/expl3.dtx    | 16 ++++++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index 06ad01d42..f867babe5 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -13,6 +13,7 @@ this project uses date-based 'snapshot' version identifiers.
 
 ### Changed
 - Distribute LaTeX3 News
+- Documentation improvements
 
 ### Fixed
 - Inherit key required/forbidden properties (see #653)
diff --git a/l3kernel/expl3.dtx b/l3kernel/expl3.dtx
index 38e114117..26df99201 100644
--- a/l3kernel/expl3.dtx
+++ b/l3kernel/expl3.dtx
@@ -365,6 +365,22 @@
 % distinguish variables from functions in the source when the |@@|
 % convention is used.
 %
+% \subsubsection{Variables: declaration}
+%
+% In well-formed \pkg{expl3} code, variables should always be declared before
+% assignment is attempted. This is true even for variable types where the
+% underlying \TeX{} implementation will allow direct assignment. This applies
+% both to setting directly (\cs{tl_set:Nn}, etc.) and to setting equal
+% (\cs{tl_set_eq:NN}, etc.).
+%
+% To help programmers to adhere to this approach, the debugging option
+% |check-declarations| may be given
+% \begin{verbatim}
+%   \debug_on:n { check-declarations }
+% \end{verbatim}
+% and will issue an error for \emph{all} assignments, at the cost of
+% performance.
+%
 % \subsubsection{Variables: scope and type}
 %
 % The \meta{scope} part of the name describes how the variable can be