注释的重要性以及注释的格式

注释并非可有可无，而是重要的局部（细节）流程澄清者。

说是局部，是因为注释是用来描述一个函数，或者一小段代码设计思想的，
对于全局的描述，很难通过短小的注释来描述清楚的，一般通过一个文档，
文档中有一些图表，如果你期望通过注释来描述结构，一个可行的方法是
遵守什么标准，例如使用模式，或者是按照一个固定的接口，例如：
我们要使用链表，遵守了某个标准提供的接口函数来操纵这个链表。
这样可以用几个字就可以包含大量的信息，从而描述清楚一个模块
（甚至整个软件）的设计方法。所以，注释一般是用来描述局部的。


澄清者的解释。我们在写软件时，一般是按照函数来划分的，当写这个函数时，
一般只有一个模糊的感觉，这个函数要做一件什么事情，至于具体如何做，
流程怎样，使用什么变量，都不会在写函数之前有很清晰的思路。
实际上，这说明在我们开始写一个函数之前，到完成函数之间，需要一些
中间过程来“推导”，如果我们把这个中间过程保留下来，将来就可以为
我们理解这一段代码提供帮助，这个中间过程就是注释。


一段注释需要有如下要素：
综述 一段描述整个函数任务的话语，包括输入，输出。
这是为了清晰总体思路，明确输入、输出用的一段话语
特别是输出，最好是用一个变量描述的
中间变量定义 这一段函数使用的中间变量及其含义，例如
用辅助寄存器AR2表示循环计数器
对于一些比较晦涩的中文名词，也可以在这里解释一下，例如：
绝对错误组号
这个我也经常省略，因为这些信息可以从“文字流程-伪代码”
中获取。
文字流程 文字描述的流程，不要具体到变量，
只要描述一句话或者一小段代码的含义即可
伪代码 用类C的代码写出文字流程，伪代码和文字流程一句对应一句。
伪代码可以精确到变量。伪代码是文字流程更进一步的描述，
更接近编程语言，但比编程语言要随意一些，不用遵守
语法规定，只要能够看懂即可。
注意：在用编程语言实现伪代码时，可能是一句伪代码，需要
好几句编程语言来实现，即编程语言和伪代码之间，不是
一一对应的关系。


下面是一段注释例子，还有改进的余地，但基本能够说明上面描述的内容：
;根据索引号ix，取出nHisErrCode0+(ix-1)*Hmi60ErrLogModeLen地址开始的，
;长度为Hmi60ErrLogModeLen的存储单元内容，写到发送缓冲区
;flow:
;取出接收缓冲区内的索引号 nComAX_S = *(RXADDRBASE+1) - 1
;计算绝对错误组号 AX=nHisErrIndex+AX If AX>10 then AX=AX-10
;检查绝对错误组号在合法范围内AX在[0,9]之间，否则AX=0
;计算错误记录组偏移量首地址nComAX_S = nComAX_S * Hmi60ErrLogModeLen
;得到错误记录组的首地址 nComAX_S = #nHisErrCode0 + nComAX_S
;AR1指向该变量地址 AR4 = nComAX_S
;拷贝从AR4一组错误记录到AR0指向的发送缓冲区，AR2为循环计数器
; for(i=0;i<Hmi60ErrLogModeLen;++i)
; *(AR0) = *(AR4)
; AR0++
; AR4++


下面我总结的注释格式标准：
summary:
xxxxxxxxxxxxxxxxx
var:
xxxxxxxxxxxxxxxxx
flow:
文字流程1 伪代码1
文字流程2 伪代码2
文字流程3 伪代码3




写代码时，可以按照伪代码的方式来实现，在两句伪代码对应的编程语言之间，用空行隔开。


另外一种方式，将“文字流程-伪代码”行，拷贝到对应的编程语言上面，不过我不喜欢这种方式，
因为将所有“文字流程-伪代码”放在一起，我可以更清晰的检查我的编程思想是否正确。


你在核对流程是否正确时，实际上可以按照上面代码“推理”过程来检查，即按照下面的顺序：
summarize
var
flow
这样，你的思想是一层层递进的，是一种逻辑推理方式实现整个函数的，而不是“测试出来”，
或者“调试出来”的。一般期望通过这种方式写出来的代码，在第一遍就是逻辑和语法上
完全正确的，不是通过编译器n次编译，n次调试，才能逼近正确的代码。