时态
为保持一致性，规格说明应使用被动语态的一般现在时。伪代码
通常情况下，应尽量减少在规格说明中使用伪代码。很多时候，只需使用描述函数操作的简单项目符号列表即可，这种方式通常已经足够，并且应被优先采用。在某些情况下，由于所描述功能本身较为复杂，伪代码可能是最合适的规格说明形式。在这些情况下，允许使用伪代码，但应尽可能简洁，理想情况下只将其限制为整体描述中的复杂部分。通用布局
下面给出的通用README 结构可用于拆解模块的规格说明。以下列表不具有约束力，且所有章节均为可选。
# {模块名称}- 模块概述## 概念- 描述整个规格说明中使用的专门概念和定义## 状态- 指定并描述预期编组到存储中的结构及其键## 状态转换- 由 hooks、消息等触发的标准状态转换操作## 消息- 指定消息结构以及预期的状态机行为## Begin Block- 指定任何 begin-block 操作## End Block- 指定任何 end-block 操作## Hooks- 描述此模块可调用或可被调用的 hooks## 事件- 列出并描述所使用的事件标签## 客户端- 列出并描述 CLI 命令以及 gRPC 和 REST 端点## 参数- 列出所有模块参数、它们的类型（使用 JSON）以及示例## 未来改进- 描述此模块未来可进行的改进## 测试- 验收测试## 附录- 规格说明其他部分引用的补充细节
键值映射的记法
在## 状态 中，应使用如下 -> 记法来描述从键到值的映射：
|。此外，也可以指定编码类型，例如：
nil 值来指定索引映射，例如：
This file intends to outline the common structure for specifications within this directory.
Tense
For consistency, specs should be written in passive present tense.Pseudo-Code
Generally, pseudo-code should be minimized throughout the spec. Often, simple bulleted-lists which describe a function’s operations are sufficient and should be considered preferable. In certain instances, due to the complex nature of the functionality being described pseudo-code may be the most suitable form of specification. In these cases use of pseudo-code is permissible, but should be presented in a concise manner, ideally restricted to only the complex element as a part of a larger description.Common Layout
The following generalizedREADME structure should be used to breakdown
specifications for modules. The following list is nonbinding and all sections are optional.
# {Module Name}- overview of the module## Concepts- describe specialized concepts and definitions used throughout the spec## State- specify and describe structures expected to be marshaled into the store, and their keys## State Transitions- standard state transition operations triggered by hooks, messages, etc.## Messages- specify message structure(s) and expected state machine behavior(s)## Begin Block- specify any begin-block operations## End Block- specify any end-block operations## Hooks- describe available hooks to be called by/from this module## Events- list and describe event tags used## Client- list and describe CLI commands and gRPC and REST endpoints## Params- list all module parameters, their types (in JSON) and examples## Future Improvements- describe future improvements of this module## Tests- acceptance tests## Appendix- supplementary details referenced elsewhere within the spec
Notation for key-value mapping
Within## State the following notation -> should be used to describe key to
value mapping:
| may be used. In addition, encoding
type may be specified, for example:
nil value, for example: