外部文档

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

编程风格文档

核对表:自说明代码

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

子程序

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

数据名

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

数据组织

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

控制

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

布局

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

设计

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

高效注释之关键

注释种类

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

高效注释

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

注释技术

注释单行

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

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

关于单行注释,下面有些指导原则:

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

行尾注释及其问题

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

何时使用行尾注释

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

注释代码段

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

注释数据声明

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

注释控制结构

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

注释子程序

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

注释类、文件和程序

标注类的一般原则

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

注释文件的一般原则

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

程序注释以书本为范例

检查表:好的注释技术

一般问题

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

语句和段落

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

数据声明

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

控制结构

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

子程序

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

文件、类和程序

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

要点

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