TLA+ 《Specifying Systems》翻译初稿——Section 3.5 Comments（注释）

本节展示了TLA+中两种注释方式:行间注释(* *)和行内注释/* 及与注释有关的几个方面：

• 注释非常重要，应尽可能多地注释、在合适地方注释以方便读者阅读规约；
• 适当地拆分模块可以使大型规约更易于阅读，首先确定阅读的顺序，再组织模块结构，最后在各模块中添加合理注释以提升阅读体验；

单从纯数学角度理解像模块 $AsynchInterface$和 $Channel$这样的简单规约也非常困难，这也是我从接口开始直观讲解的原因，这种讲解可使您更容易理解模块中的公式 $Spec$，这是实际规约。每个规约都应附有非正式的行文说明，该解释可以在随附的文档中，也可以作为注释包含在规约中。

下面的图3.3展示了如何通过注释帮助解释 $HourClock$模块中的小时时钟规约。在 $TLATEX$排版版本中，注释通过使用其他字体与规约本身区分开。如图所示，TLA+提供了两种以ASCII版本编写注释的方法。注释可能会出现在“（”和“）”之间的任何地方，行尾注释以“\*”开头。注释可能是嵌套的，因此您可以通过将规约的一部分括在（和），即使该部分包含注释。

注释几乎总是单独出现在一行中或一行的末尾。我在 $HCnxt$和 $\triangleq$之间添加了一条注释，以表明可以这么做。

为了节省空间，我将在示例规约中添加少量注释，但是规约中应该包含很多注释，即使有随附的描述系统的文档，也需要注释帮助读者理解规约是如何将该描述形式化的。

注释可以帮助解决由规约的逻辑结构引起的问题。必须先声明或定义符号，之后才能使用它。在 $Channel$模块中， $Spec$的定义必须遵循 $Next$的定义，而后者必须遵循 $Send$和 $Rcv$的定义。但是，通常最容易理解的方式是自上而下的系统描述。我们可能首先要阅读 $Data$和 $chan$的声明，然后是 $Spec$的定义，接着是 $Init$和 $Next$的定义，最后才是 $Send$和 $Rcv$的定义。换句话说，我们希望或多或少从下至上地阅读规约。对于较短的如 $Channel$这样的模块来说，这很容易完成；但对于较长的规约就不那么方便了。我们可以使用注释来指导读者阅读更长的规约。例如，我们可以在 $Channel$模块中的 $Send$定义之前加上注释：

接下来的动作 $Send$和 $Rcv$是 $\footnotesize{next-state}$动作 $Next$的析取词。

模块结构还允许我们指定读取规约的顺序。例如，我们可以通过将 $HourClock$模块拆分为三个单独的模块来重写小时时钟规约：

• $HCVar$模块中声明变量 $hr$；
• $HCActions$模块中引入 $Naturals$和 $HCVar$模块，并定义 $HCini$和 $HCnxt$；
• $HCSpec$模块引入模块 $HCActions$，定义公式 $HC$并声明类型正确性定理。

$\text{EXTENDS}$关系隐含了模块的逻辑顺序： $HCVar$在 $HCActions$之前， $HCActions$在 $HCSpec$之前。但是不必按此顺序阅读模块。可以告知读者首先阅读 $HCVar$，然后阅读 $HCSpec$，最后才到 $HCActions$。下面第4章引入的 $\text{INSTANCE}$提供了另一种用于模块化规约的工具。

以这种方式拆分像 $HourClock$这样的微小规约看起来很荒谬，但是适当地拆分模块可以使大型规约更易于阅读。在编写规约时，您应该先决定按什么顺序阅读最舒服，然后再设计组织模块结构，以方便按设定的顺序阅读，同时也允许按从头至尾的顺序阅读单个模块。最后，您应该确保以适当的顺序阅读不同的模块时，其中的注释能提升阅读体验。