《代码大全》阅读笔记-32-自说明代码

核对表（自说明代码）

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

子程序

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

数据名

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

数据组织

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

控制

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

布局

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

设计

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

核对表（好的注释技术）

一般问题

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

语旬和段落

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

数据声明

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

控制结构

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

子程序

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

文件、类和程序

• 程序有简短的文档（就像在“以书本为范例”中说明的那样）给出程序组织的概述吗？
• 每个文件的用途都有说明吗？
• 作者姓名、email及电话号码在代码清单中都有吗？

要点

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