☰

在 LaTeX 文档中撰写注释的最佳实践

tag-icon • tag-icon best-practices comments
在 LaTeX 文档中撰写注释的最佳实践

我想了解在 LaTeX 文档中使用注释的推荐做法。

一些编程语言对于如何在源代码中使用注释有非常清晰的说明：例如，[这里] 是关于在 OCaml 中使用注释的一些指导原则，以及 [这里] 是一些针对 Java 的指导原则。但是 LaTeX 呢？

以下是答疑者可能想要解答的几个问题：

  • 我应该在我定义的每个命令的上方/下方/内部添加注释吗？
  • 注释应该放在现有行的末尾，还是单独占据一行？
  • 是否有一种可接受的方式使用注释来定义命令的每个参数？
  • 那么使用注释符号行作为分段装置怎么样？
  • 应该在文件顶部放置什么样的注释？

下面是我的一些代码（节选），其中大量使用了注释。我认为它可能是一个有用的起点。

\documentclass{article}

% ===================================================================
% TODO LIST
%
% * make "draw grid" key work properly
%
% * make a macro for partially-rounded rectangle

\usepackage{tikz}
\usetikzlibrary{showgrid}
\usetikzlibrary{calc}
\usepackage{etextools}

\makeatletter

% ===================================================================
% GENERAL-PURPOSE COMMANDS

% Extension of the ExpandNextTwo command provided by etextools
\def\ExpandNextThree#1#2#3#4{%
  \ExpandNext{\ExpandNext{\ExpandNext{#1}{#2}}{#3}}{#4}}

% ===================================================================
% CONSTANTS

\newcommand\jusColor{black!50} % bg colour of "justification" steps
\newcommand\comColor{black}    % bg colour of "command" steps 

% ===================================================================
% MINOR COMMANDS

% The expression
%   \@defineShape{foo}{34}{57}
% expands to the following definitions
%   \xdef\shapes@foo@left{34}
%   \xdef\shapes@foo@right{57}
\newcommand*\@defineShape[3]{%
  \expandafter\xdef\csname shapes@#1@left\endcsname{#2}
  \expandafter\xdef\csname shapes@#1@right\endcsname{#3}
}

\newenvironment{mydiagram}[1][]{%
  %
  % Process keys
  \pgfkeys{/mydiagram/.cd,scale=1,start shapes={},#1}
  %
  % Nudge vertical cursor up a bit. This is a hack to 
  % counteract the fact that the first row does not have
  % any steps in it. Without this hack, the labels in 
  % the first row would be printed too far down.
  \setcounter{VCursor}{-\defaultStepHeight}
  %
  % Make the \\ command a synonym for \finishrow. The
  % reason for this is mainly to exploit the syntax
  % highlighting in AucTeX, which emphasises \\ commands.
  \renewcommand\\{\finishrow}

答案1

Donald E. Knuth 不仅为我们带来了 TeX，他还被认为是文学编程. 在准备 LaTeX 包时，也应用了文学编程的原理。

.dtx 文件以简单的英语注释形式包含对宏的解释，同时还穿插了 LaTeX 代码中真实宏的片段。从此 .dtx 文件可生成包代码和文档 PDF。

为了开始使用 .dtx 文件，我建议使用CTAN 支持包生成由怀博·德克尔。

在此处输入图片描述

相关内容