外部文档
- 单元开发文件夹；
- 是一种非正式文档，其中包含了供开发者在变成期间使用的记录；
- 详细设计文档；
- 是低层次设计文档，描述在类层或子程序层的设计决定，曾考虑过其他方案，以及采用所选方案的理由。
编程风格文档
核对表：自说明代码
类
- [ ] 你的类接口体现出某种一致的抽象吗？
- [ ] 你的类名有意义吗？能表明其中心意图吗？
- [ ] 你的类接口对于如何使用该类显而易见吗？
- [ ] 你的类接口能抽象到不需要考虑其实现过程吗？能把类看作是黑盒吗？
子程序
- [ ] 你的每个子程序名都能准确地指示该子程序确切干些什么吗？
- [ ] 你的各子程序的任务明确吗？
- [ ] 若各子程序中自成一体后更有用，你都将其个子独立出来了吗？
- [ ] 每个子程序的接口都清晰明了吗？
数据名
- [ ] 类型名描述有助于说明数据声明吗？
- [ ] 你的变量名有意义吗？
- [ ] 变量只用在其名字所代表意义的场合吗？
- [ ] 你的循坏变量名能给出更多信息，而不是i、j、k之类的吗？
- [ ] 你用了名字有意义的枚举类型，而非临时拼凑的标识或者布尔变量吗？
- [ ] 用具名常量代替神秘数值或者字符串了吗？
- [ ] 你的命名规范能区分类型名、枚举类型、具名常量、局部变量、类变量即全局变量吗？
数据组织
- [ ] 你根据编程清晰的需要，使用了额外变量来提高清晰度吗？
- [ ] 你对某变量的引用集中吗？
- [ ] 数据类型简化到了最低复杂度吗？
- [ ] 你是通过抽象访问子程序来访问复杂数据吗？
控制
- [ ] 代码中的正常执行路径很清晰吗？
- [ ] 相关语句放在一起了吗？
- [ ] 相对独立的语句组打包为子程序了吗？
- [ ] 正常情况的处理位于
if语句之后，而非在else子句中吗？ - [ ] 控制结构简单明了，以使复杂度最低吗？
- [ ] 每个循环完成且仅完成一个功能，是像定义良好的子程序那么做吗？
- [ ] 嵌套层次是最少吗？
- [ ] 逻辑表达式通过额外添加布尔变量、布尔函数和功能表简化了吗？
布局
- [ ] 程序的布局能表现出其逻辑结构吗？
设计
- [ ] 代码直截了当吗？是不是避免了自作聪明或新花样？
- [ ] 实现细节尽可能隐藏了吗？
- [ ] 程序是尽可能采用问题领域的术语，而非按照计算机科学或者编程语言的术语编写的吗？
高效注释之关键
注释种类
- 重复代码；
- 解释代码；
- 代码标记；
- 概述代码；
- 代码意图说明；
- 传达代码无法表述的信息；
高效注释
- 采用不会打断或抑制修改的注释风格；
- 用伪代码编程法减少注释时间；
- 将注释集成到你的开发风格中；
- 性能不是逃避注释的好借口。
注释技术
注释单行
对于好的代码，很少需要注释单条语句。要注释一行代码，有两种可能的理由：
- 该行代码太复杂，因而需要解释；
- 改行语句出过错，你想记下这个错。
关于单行注释，下面有些指导原则：
- 不要随意添加无关注释；
行尾注释及其问题
- 不要对单行代码做行尾注释；
- 不要对多行代码做行尾注释。
何时使用行尾注释
- 行尾注释用于数据声明；
- 避免用行尾注释存放维护注记；
- 用行尾注释标记块尾。
注释代码段
- 注释应表达代码的意图；
- 代码本身应尽力做好说明；
- 注释代码段时应注重“为何做”而不是“怎么做”；
- 用注释为后面的内容做铺垫；
- 让每个注释都有用；
- 说明非常规做法；
- 别用缩略语；
- 将主次注释区分开；
- 错误或语言环境独特点都要加注释；
- 给出违背良好编程风格的理由；
- 不要注释投机取巧的代码，应重写之。
注释数据声明
- 注释数值单位；
- 对数值的允许范围给出注释；
- 注释编码含义；
- 注释对输入数据的限制；
- 注释“位标志”；
- 将与变量有关的注释通过变量名关联起来；
- 注释全局数据。
注释控制结构
- 应在每个if、case、循环或者代码段前面加上注释；
- 应在每个控制结构后加上注释；
- 将循环结束处的注释堪称时代码太复杂的征兆。
注释子程序
- 注释应靠近其说明的代码；
- 在子程序上部用一两句话说明之；
- 在声明参数处注释这些参数；
- 利用诸如Javadoc之类的代码说明工具；
- 分清输入和输出数据；
- 注释接口假设；
- 对子程序的局限性作注释；
- 说明子程序的全局效果；
- 记录所用算法的来源；
- 用注释标记程序的各部分；
注释类、文件和程序
标注类的一般原则
- 说明该类的设计方法；
- 说明局限性、用法假设等；
- 注释类接口；
- 不要在类接口处说明实现细节。
注释文件的一般原则
- 说明各文件的意图和内容；
- 将姓名、电子邮件及电话号码放到注释块中；
- 包含把版本控制标记；
- 请在注释块中包含法律通告；
- 将文件命名为与其内容相关的名字。
程序注释以书本为范例
检查表：好的注释技术
一般问题
- [ ] 别人拿起你的代码能立刻明白其意吗？
- [ ] 你的注释是在解释代码用意，或概括代码在做什么，而非简单重复代码吗？
- [ ] 采用了伪代码编程来减少注释时间吗？
- [ ] 是重写有玄机的代码，而非为其做注释吗？
- [ ] 你的注释能否同代码一起更新？
- [ ] 注释清楚正确吗？
- [ ] 你的注释风格便于修改注释吗？
语句和段落
- [ ] 代码避免用行尾注释了吗？
- [ ] 注释是着力说明为什么而非怎么样吗？
- [ ] 每个注释为将要阅读代码的人们都做好准备了吗？
- [ ] 每个注释都有其用处吗？删掉抑或改进了多余的、无关紧要的或随意的注释没有？
- [ ] 是否注释了代码的非常规之处？
- [ ] 避免使用缩略语了吗？
- [ ] 主次注释区别明显了吗？
- [ ] 含错代码和未公开的代码特性有注释吗？
数据声明
- [ ] 对数据声明的注释说明了数值单位吗？
- [ ] 数值数据的取值范围注释出来了吗？
- [ ] 注释出了编码含义吗？
- [ ] 对输入数据的限制有注释吗？
- [ ] 对位标志做注释了吗？
- [ ] 在各全局变量声明的地方对其做注释了吗？
- [ ] 各全局变量是通过命名规范、注释来标识其意义吗？
- [ ] 神秘数值是否以具名常量或变量代替，而非指示标注之？
控制结构
- [ ] 控制语句都注释了吗？
- [ ] 冗长或者复杂的控制结构结尾处有注释吗？抑或可能的话，简化之从而省去注释了吗？
子程序
- [ ] 各子程序的意图都注释了吗？
- [ ] 子程序的其他有关情况（诸如输入数据、接口假设、局限性、纠错、全局效果和算法来源）都注释出来了吗？
文件、类和程序
- [ ] 程序有简短的文档给出程序的组织概述吗？
- [ ] 每个文件的用途都有说明吗？
- [ ] 作者姓名、email及电话好吗在代码清单中都有吗？
要点
- 该不该注释是个需要认真对待的问题。差劲的注释指挥浪费时间，帮倒忙；好的注释才有价值；
- 源代码应当含有程序大部分的关键信息。只要程序依然在用，源代码比其他资料都能保持更新，故而将重要信息融入diamagnetic是很有用处的；
- 好代码本身就是最好的说明。如果代码太糟，需要大量注释，应先试着改进代码，直至无需过多注释为止；
- 注释应该说出代码无法说出的东西——例如概述或用意等信息；
- 有的注释风格需要许多重复性劳动，应舍弃之，改用易于维护的注释风格。