1. 读后笔记

1.1. 可读性基本定理

代码的写法应当使别人理解它所需的时间最小化,这被称为可读性基本定理

1.2. 将信息包含在变量名

1.2.1. 选择更专业的词汇

如 send 被 deliver 或 dispatch等替换

1.2.2. 尽可能避免无意义的变量名,尽管只是临时存储

如a, i ,tmp 等

1.2.3. 名字附带更多的信息

如 html -> html_utf8 password -> plaintext_password

1.2.4. 名字的长度

指导原则: 在小的作用域里可以使用短的名字,而标示一个比较大的作用域,那么名字中应当包含足够多的信息以供释义

  • 如果缩写为人公知,则应用缩写
  • 舍弃部分没用的单词

1.2.5. 名字的格式来传递含义

有目的的使用大小写和下划线 如Python中常在方法或变量前加 "_" 来标示其为内部方法或变量

1.3. 不会误解的名字

因为英文多义性,所以起名前最好保证其释义为多数人熟知 当表示一个值的上限和下限的时候,max和min

  • 对于包含的范围,first和last
  • 对于包含/排除的范围 begin和end
  • 为布尔值命名的时,使用is和has来表示

1.4. 代码的审美

三条原则:

  1. 使用一致的布局
  2. 让相似的代码看上去相似
  3. 把相关的代码行分组,形成代码块

方法:

  1. 重新安排换行来保持一致和紧凑 P39
  2. 用方法来整理不规则的东西(利用语言提供的特定方法来实现) P40
  3. 在需要时使用列对齐(利用空白使上下对齐) (仅仅作为推荐,因为部分语言这样做可能导致异常)
  4. 选择一个有意义的排序方式,并保持一致(如配置文件中引入许多配置项,同一类配置项内共有变量名按字母顺序排序)
  5. 充分利用换行来将代码分块分组
  6. 个人风格与一致性 一致的风格比“正确”的风格更重要

1.5. 注释的模样

1.5.1. 关键思想: 注释的目的是尽量帮助读者了解作者的所思所想

什么时候不需要注释:

  1. 不要为那些从代码本身就能迅速推断的事实去写注释
  2. 不要为了注释而注释(如老板要求)
  3. 不要给不好的名字加注释--应该改好名字 (比如函数名,假如函数名十分糟糕,那么应该换个更能表述这段代码的好名字而不是写堆注释来解释这段代码为什么叫这个名字)

1.5.2. 什么时候需要注释:

  1. 记录当时的想法(特别是偏算法部分的代码)
  2. 加入“导演评论” 对此处代码给出自己的见解,以防止后继者无谓的优化而浪费时间 或 以为这段代码有隐藏的BUG而浪费时间去试图找到能让它失败的测试参数或用例
  3. 为代码的瑕疵而写注释 (通用的瑕疵标记在下)
  4. 给部分常量加注释,如释义为何该常量定义这个范围

    程序员中流行的标记:

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

应该把代码将来应该如何改动的想法用注释记录下来

1.5.3. 从读者的角度

  1. 在注释回答难以理解的意料之中的提问
  2. 公布可能的陷阱
  3. 全局观的注释 常用于文件/类的级别使用全局观 如表述该函数在系统中所在的位置,起到的作用
  4. 总结性的注释 常用于包含几大块的长函数中 如在某函数前加一句注释: 以下的函数都是为文件系统的某组件底层

1.5.4. 注释应该怎么写

  1. 注释应该保持紧凑
  2. 避免使用不明确的代词
  3. 精确地描述函数的行为
  4. 用输入/输出的例子来说明特别的情况 例子应尽可能包含可能出现的情况,如边界情况,是否可重复,是否输出结果已排序,如果返回值是输入值中的某一个那么输出值是计算得到的结果还是筛选出来的结果
  5. 使用更专业或者信息量更高的词语

results matching ""

    No results matching ""

    results matching ""

      No results matching ""