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

Posted Tacey Wong

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了《代码大全》阅读笔记-32-自说明代码相关的知识,希望对你有一定的参考价值。

核对表(自说明代码)

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

子程序

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

数据名

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

数据组织

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

控制

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

布局

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

设计

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

核对表(好的注释技术)

一般问题

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

语旬和段落

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

数据声明

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

控制结构

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

子程序

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

文件、类和程序

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

要点

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

以上是关于《代码大全》阅读笔记-32-自说明代码的主要内容,如果未能解决你的问题,请参考以下文章

读书笔记2-《代码大全2》

《代码大全》阅读笔记-15-使用条件语句

代码大全阅读笔记01

代码大全阅读笔记02

《代码大全2》阅读笔记05

代码大全阅读笔记03