第三十二章 自说明代码

外部文档

• 单元开发文件夹；
  • 是一种非正式文档，其中包含了供开发者在变成期间使用的记录；
• 详细设计文档；
  • 是低层次设计文档，描述在类层或子程序层的设计决定，曾考虑过其他方案，以及采用所选方案的理由。

编程风格文档

核对表：自说明代码

类

• 你的类接口体现出某种一致的抽象吗？
• 你的类名有意义吗？能表明其中心意图吗？
• 你的类接口对于如何使用该类显而易见吗？
• 你的类接口能抽象到不需要考虑其实现过程吗？能把类看作是黑盒吗？

子程序

• 你的每个子程序名都能准确地指示该子程序确切干些什么吗？
• 你的各子程序的任务明确吗？
• 若各子程序中自成一体后更有用，你都将其个子独立出来了吗？
• 每个子程序的接口都清晰明了吗？

数据名

• 类型名描述有助于说明数据声明吗？
• 你的变量名有意义吗？
• 变量只用在其名字所代表意义的场合吗？
• 你的循坏变量名能给出更多信息，而不是i、j、k之类的吗？
• 你用了名字有意义的枚举类型，而非临时拼凑的标识或者布尔变量吗？
• 用具名常量代替神秘数值或者字符串了吗？
• 你的命名规范能区分类型名、枚举类型、具名常量、局部变量、类变量即全局变量吗？

数据组织

• 你根据编程清晰的需要，使用了额外变量来提高清晰度吗？
• 你对某变量的引用集中吗？
• 数据类型简化到了最低复杂度吗？
• 你是通过抽象访问子程序来访问复杂数据吗？

控制

• 代码中的正常执行路径很清晰吗？
• 相关语句放在一起了吗？
• 相对独立的语句组打包为子程序了吗？
• 正常情况的处理位于if语句之后，而非在else子句中吗？
• 控制结构简单明了，以使复杂度最低吗？
• 每个循环完成且仅完成一个功能，是像定义良好的子程序那么做吗？
• 嵌套层次是最少吗？
• 逻辑表达式通过额外添加布尔变量、布尔函数和功能表简化了吗？

布局

• 程序的布局能表现出其逻辑结构吗？

设计

• 代码直截了当吗？是不是避免了自作聪明或新花样？
• 实现细节尽可能隐藏了吗？
• 程序是尽可能采用问题领域的术语，而非按照计算机科学或者编程语言的术语编写的吗？

高效注释之关键

注释种类

• 重复代码；
• 解释代码；
• 代码标记；
• 概述代码；
• 代码意图说明；
• 传达代码无法表述的信息；

高效注释

• 采用不会打断或抑制修改的注释风格；
• 用伪代码编程法减少注释时间；
• 将注释集成到你的开发风格中；
• 性能不是逃避注释的好借口。

注释技术

注释单行

对于好的代码，很少需要注释单条语句。要注释一行代码，有两种可能的理由：

1. 该行代码太复杂，因而需要解释；
2. 改行语句出过错，你想记下这个错。

关于单行注释，下面有些指导原则：

• 不要随意添加无关注释；

行尾注释及其问题

• 不要对单行代码做行尾注释；
• 不要对多行代码做行尾注释。

何时使用行尾注释

• 行尾注释用于数据声明；
• 避免用行尾注释存放维护注记；
• 用行尾注释标记块尾。

注释代码段

• 注释应表达代码的意图；
• 代码本身应尽力做好说明；
• 注释代码段时应注重“为何做”而不是“怎么做”；
• 用注释为后面的内容做铺垫；
• 让每个注释都有用；
• 说明非常规做法；
• 别用缩略语；
• 将主次注释区分开；
• 错误或语言环境独特点都要加注释；
• 给出违背良好编程风格的理由；
• 不要注释投机取巧的代码，应重写之。

注释数据声明

• 注释数值单位；
• 对数值的允许范围给出注释；
• 注释编码含义；
• 注释对输入数据的限制；
• 注释“位标志”；
• 将与变量有关的注释通过变量名关联起来；
• 注释全局数据。

注释控制结构

• 应在每个if、case、循环或者代码段前面加上注释；
• 应在每个控制结构后加上注释；
• 将循环结束处的注释堪称时代码太复杂的征兆。

注释子程序

• 注释应靠近其说明的代码；
• 在子程序上部用一两句话说明之；
• 在声明参数处注释这些参数；
• 利用诸如Javadoc之类的代码说明工具；
• 分清输入和输出数据；
• 注释接口假设；
• 对子程序的局限性作注释；
• 说明子程序的全局效果；
• 记录所用算法的来源；
• 用注释标记程序的各部分；

注释类、文件和程序

标注类的一般原则

• 说明该类的设计方法；
• 说明局限性、用法假设等；
• 注释类接口；
• 不要在类接口处说明实现细节。

注释文件的一般原则

• 说明各文件的意图和内容；
• 将姓名、电子邮件及电话号码放到注释块中；
• 包含把版本控制标记；
• 请在注释块中包含法律通告；
• 将文件命名为与其内容相关的名字。

程序注释以书本为范例

检查表：好的注释技术

一般问题

• 别人拿起你的代码能立刻明白其意吗？
• 你的注释是在解释代码用意，或概括代码在做什么，而非简单重复代码吗？
• 采用了伪代码编程来减少注释时间吗？
• 是重写有玄机的代码，而非为其做注释吗？
• 你的注释能否同代码一起更新？
• 注释清楚正确吗？
• 你的注释风格便于修改注释吗？

语句和段落

• 代码避免用行尾注释了吗？
• 注释是着力说明为什么而非怎么样吗？
• 每个注释为将要阅读代码的人们都做好准备了吗？
• 每个注释都有其用处吗？删掉抑或改进了多余的、无关紧要的或随意的注释没有？
• 是否注释了代码的非常规之处？
• 避免使用缩略语了吗？
• 主次注释区别明显了吗？
• 含错代码和未公开的代码特性有注释吗？

数据声明

• 对数据声明的注释说明了数值单位吗？
• 数值数据的取值范围注释出来了吗？
• 注释出了编码含义吗？
• 对输入数据的限制有注释吗？
• 对位标志做注释了吗？
• 在各全局变量声明的地方对其做注释了吗？
• 各全局变量是通过命名规范、注释来标识其意义吗？
• 神秘数值是否以具名常量或变量代替，而非指示标注之？

控制结构

• 控制语句都注释了吗？
• 冗长或者复杂的控制结构结尾处有注释吗？抑或可能的话，简化之从而省去注释了吗？

子程序

• 各子程序的意图都注释了吗？
• 子程序的其他有关情况（诸如输入数据、接口假设、局限性、纠错、全局效果和算法来源）都注释出来了吗？

文件、类和程序

• 程序有简短的文档给出程序的组织概述吗？
• 每个文件的用途都有说明吗？
• 作者姓名、email及电话好吗在代码清单中都有吗？

要点

• 该不该注释是个需要认真对待的问题。差劲的注释指挥浪费时间，帮倒忙；好的注释才有价值；
• 源代码应当含有程序大部分的关键信息。只要程序依然在用，源代码比其他资料都能保持更新，故而将重要信息融入diamagnetic是很有用处的；
• 好代码本身就是最好的说明。如果代码太糟，需要大量注释，应先试着改进代码，直至无需过多注释为止；
• 注释应该说出代码无法说出的东西——例如概述或用意等信息；
• 有的注释风格需要许多重复性劳动，应舍弃之，改用易于维护的注释风格。