12bet,读书笔记

表面层次的改进

12bet,代码应当易于理解

关键思想:代码应当易于理解

关键思想:代码的写法应当使别人理解它所需的时间最小化

12博体育,尽管减少代码行数是一个好目标,但把理解代码所需的时间最小化是一个更好的目标

12博体育,把信息装到名字里

关键思想:把信息装入名字中

关键思想:清晰和精确比装可爱好

12bet,选择专业的词

12bet,要选择非常专业的词,并且避免使用“空洞”的词

找到更有表现力的词

同义词有很多,尽量找到最精确的描述

避免像tmp和retval这样泛泛的名字

名字要尽量表明实体或行为,不要使用泛泛的空洞的名字

如果非要使用,必须有一个理由

循环迭代器

迭代器在表明迭代功能的同时,也应当表明迭代的实体

用具体的名字代替抽象的名字

在给变量、函数或者其他元素命名时,要把它描述得更具体而不是更抽象

为名字附带更多信息

如果关于一个变量有什么重要事情的读者必须知道,那么是值得把额外的“词”添加到名字中的

如果你的变量是一个度量的话(如时间长度或者字节数),那么最好把名字带上它的单位

若存在不确定性,比如有多种状态或形式,就应该将信息包含在名称中,对状态或形式做区分

名字应该有多长

名字不能太长, 名字越长越难记,在屏幕上占的地方也越大,可能会产生更多的换行

小的作用域里可以使用短的名字,所有的信息(变量的类型、它的初值、如何析构等)都很容易看到,所以可以用很短的名字

如果一个标识符有较大的作用域,那么它的名字就要包含足够的信息以便含义更清楚

首字母缩略词和缩写

经验原则是:团队的新成员是否能理解这个名字的含义?如果能,那可能就没有问题。

丢掉没用的词

利用名字的格式来传递含义

对于下划线、连字符和大小写的使用方式也可以把更多信息装到名字中

其他格式规范

注通过业内或团队内部定义一些规范来表明意义,比如类名首字母大写,jquery对象以$开头

总结

  • 使用专业的单词
  • 避免空泛的名字
  • 使用具体的名字来更细致地描述事物
  • 给变量名带上重要的细节
  • 为作用域大的名字采用更长的名字
  • 有目的地使用大小写、下划线等

不会误解的名字

避免二义性

关键思想: 要多问自己几遍:“这个名字会被别人解读成其他的含义吗?”要仔细审视这个名字

例如Filter(),“filter”是个二义性单词。我们不清楚它的含义到底是“挑出”还是“减掉”

注注意名称的二义性,避免对行为产生误解

  • 推荐用min和max来表示(包含)极限:防止出现大小差一问题,避免混淆大于和大于等于
  • 推荐用first和last来表示包含的范围
  • 推荐用begin和end来表示包含/排除范围

给布尔值命名

当为布尔变量或者返回布尔值的函数选择名字时,要确保返回true和false的意义很明确

通常来讲,加上像is、has、can或should这样的词,可以把布尔值变得更明确。

最好避免使用反义名字

与使用者的期望相匹配

注注意业内的一些常用命名规则,这些命名通常已形成习惯,尽量不要违背这些习惯

审美

重新安排换行来保持一致和紧凑

用方法来整理不规则的东西

注对于一些一致性的行为,可以通过创建函数来整理,使得布局更整齐一致

在需要时使用列对齐

整齐的边和列让读者可轻松地浏览文本

有时你可以借用“列对齐”的方法来让代码易读。建立和维护对齐的工作量很大。在改动时它造成了更多的“不同”,对一行的改动可能会导致另外5行也要改动

选一个有意义的顺序,始终一致地使用它

在很多情况下,代码的顺序不会影响其正确性。不要随机地排序,把它们按有意义的方式排列会有帮助

把声明按块组织起来

大脑很自然地会按照分组和层次结构来思考,因此你可以通过这样的组织方式来帮助读者快速地理解你的代码。

把代码分成“段落”

书面文字要分成段落是由于它是一种把相似的想法放在一起并与其他想法分开的方法。它提供了可见的“脚印”,如果没有它,会很容易找不到你读到哪里了

这便于段落之间的导航。因为同样的原因,代码也应当分成“段落”

给每个段落加了一条总结性的注释,这也会帮助读者浏览代码

个人风格与一致性

关键思想: 一致的风格比“正确”的风格更重要。

该写什么样的注释

关键思想: 注释的目的是尽量帮助读者了解得和作者一样多。

什么不需要注释

关键思想: 不要为那些从代码本身就能快速推断的事实写注释。

不要为了注释而注释

不要给不好的名字加注释——应该把名字改好。 一个好的名字比一个好的注释更重要,因为在任何用到这个函数的地方都能看得到它。

好代码>坏代码+好注释

记录你的思想

很多好的注释仅通过“记录你的想法”就能得到,也就是那些你在写代码时有过的重要想法。应该在代码中也加入注释来记录你对代码有价值的见解。

为代码中的瑕疵写注释

注将代码中的问题通过注释记录下来,并把改动的建议也写在注释中,能给后人宝贵的意见

标记

  • TODO:我还没有处理的事情
  • FIXME:已知的无法运行的代码
  • HACK:对一个问题不得不采用的比较粗糙的解决方案
  • XXX:危险!这里有重要的问题

给常量加注释

注常量,如果名字不足以说明常量的由来,就应当添加注释标明由来

站在读者的角度

  • 意料之中的提问:在读者会产生困惑的地方加上注释
  • 公布可能的陷阱:告知代码在哪些情况下会产生问题
  • “全局观”注释:一些全局层面的注释能够帮助读者快速理解代码的功能,非常有帮助
  • 总结性注释:对代码做什么、怎么做、为什么做总结

最后的思考——克服“作者心理阻滞”

写注释这件事拆成了几个简单的步骤:

  1. 不管你心里想什么,先把它写下来
  2. 读一下这段注释,看看有没有什么地方可以改进。
  3. 不断改进。

写出言简意赅的注释

关键思想: 注释应当有很高的信息/空间率

  • 让注释保持紧凑
  • 避免使用不明确的代词:注注释中的各个成员应当清晰明确,防止出现误解
  • 润色粗糙的句子:在很多情况下,让注释更精确的过程总是伴随着让注释更紧凑
  • 精确地描述函数的行为
  • 用输入/输出例子来说明特别的情况:对于注释来讲,一个精心挑选的输入/输出例子比千言万语还有效
  • 声明代码的意图:从更高的层次解释了这段程序在做什么。这更符合程序员写这段代码时的想法。
  • “具名函数参数”的注释:注参数为常数时应当给出注释进行说明
  • 采用信息含量高的词:通常会有专门的词或短语来描述这种模式/定式。使用这些词会让你的注释更加紧凑