代码可读性

Question

代码应利于理解。代码的写法应当使别人理解它所需的时间最小化。

表面层次的改进

把信息写到名字

• 选择专业的词
  • getPage(url)
  • FetchPage(url)
  • Download(url)

  寻找更有清晰、准确、具体的词语

  单词	选择
  send	deliver、dispatch、announce、distribute、route
  find	search、extract、locate、recover
  start	launch、create、begin、open
  make	create、set up、build、generate、compose、add、new

• 避免泛泛的名字
  • tmp、retval
  • tmp 只适用于短期存在的临时存储。
  • 循坏迭代中的经典 i、j、k 变量，可以使用 clubs[ci].members[mi]==users[ui] 的 ci、mi、ui，这样可以不容易弄错下标。
• 使用前缀或者后缀
  • 假设有个 id 为十六进制的格式，可以命名 hex_id。
  • 形参后缀命名：start(int delay) => start(int delay_ms)
  • 未处理的变量，使用 raw_
• 决定名字的长度
  • 小的作用域可以使用短的命名。因为已经有了较为具体的上下文信息。
  • 较外层的作用域需要足够长的命名。避免费解的缩写，这样会增加理解难度。
  • 取消不必要的词。例如 convertToString() => toString()
• 利用名字的格式
  • 小驼峰
  • 下划线

不会误解的名字

1. 推荐 min 或 max 表示极限。
2. 推荐 first 和 last 表示左包含、右包含的范围。

   first       last
   | a | b | c | d |  |
   

3. 推荐 begin 或 end 表示左包含、右排除的范围。

   begin            end
   | a | b | c | d |   |
   

4. 布尔值命名。使用 is、has、should、can 这样的前缀。同时避免反义词。

审美

• 布局一致
• 代码类似
• 相关代码分组

一致的风格比个性化的风格重要。

代码注释

• 过于直白的方法不必要注释。
• 好代码> 坏代码+好注释>坏代码
• 代码缺陷的常见标记

  标记	标记的意义
  TODO	未做的事情
  FIXME	已知的 bug
  HACK	比较粗糙的解决方案
  XXX	危险的问题、警告

• 常量加必要的注释。
• 代码注释能否帮助读者重现作者的实现思路。
• 好的代码注释的原则：
  • 避免 it 这种不明确的代词。
  • 精确描述函数的行为，力求紧凑简练。
  • 输入输出用例需要具有代表性。
  • 声明代码的高层次意图，而不是明显的细节。
  • 嵌入式注释说明参数意义。

简化循坏和逻辑

优化控制流

• 选择合适的 if/else 语句块的顺序
• 从函数中尽早返回，例如卫语句。
• 最小化嵌套，可以通过尽早返回来实现。
• 在 for each 中，提早返回的技术是 continue。
• 尽量避免 do/while，goto，三目元算符的使用。

拆分长表达式

• 德摩根定理
  • not(a or b) <=> (not a) and (not b)
  • not(a and b) <=> (not a) or (not b)
• 使用总结性的变量：解释变量。
• 简化复杂难懂的逻辑：考虑取反的思路。

变量可读性

1. 减少变量。
2. 缩小变量的作用域。

重新组织代码

抽取代码

1. 抽取工具类代码。
2. 简化已有接口。
3. 重构某些函数。

保持专注

1. 分解为函数
2. 分成段落

保持逻辑清晰

将代码的思路描述成自然语言。

少写代码

1. 最小化需求，不要过度设计。
2. 保持小的代码库：减少重复、无用代码，项目拆分子模块。
3. 熟悉周边的标准库/工具库的 API，不要直接造轮子。
4. 像达尔文进化一样的代码才有价值。

测试

测试与可读性

• 让测试易于阅读：每个测试输入输出可以用一行代码描述。
• 让错误信息具有可读性
  • input：...
  • expected output: ...
  • actual output: ...
• 更好的测试输入：简单，具有代表性。例如考虑重复元素，负值，空值，0 值等。
• 为测试函数命名
  • Test_SortAndFilterDocs()
  • Test_SortAndFilterDocs_BasicSorting()