代码整洁（2）：函数、注释

《代码整洁之道》Clean Code A Handbook of Agile Software Craftsmanship 读书笔记

函数

• 短小
  • 函数的第一规则是要短小。第二条规则是还要更短小。
  • if语句、else语句、while语句等，其中代码块应该只有一行。该行大抵应该是一个函数调用语句。这样不但能保持函数短小，而且，因为块内调用的函数拥有较具说明性的名称，从而增加了文档上的价值。（虽然在实际开发中也听别人说过尽量少用if等语句。但是，像书中描述的这种代码结构还是没有见到过，这种结构衍生出的函数会非常多吧！）
• 只做一件事
  • 函数应该做一件事。做好这件事。只能做这一件事。（一件事不是意义上的一件事，而是一个完整的流程。）
• 每个函数一个抽象层级
  • 要确保函数只做一件事，函数中的语句都要在同以抽象层级上。（关于抽象层级，大体理解为，抽象层级越高，概括性更强，具体的信息越少。抽象层级越低，具体信息越多，概括性也就越弱。抽象层次概念）

比如你要从家出发去商店
“较低的”抽象层次就是指：
{
  1.打开家门
  2.坐上出租车
  3.到了路口右转
  4.继续前进100米，
  5.停在路右边
  6.走进商店
}

相对而言，“更高的”抽象层次就是指：
{
   从家里出发去商店
}

• switch 语句
  • 将 seitch 语句埋到抽象工厂底下，不让任何人看到。
• 使用描述性名称
  • 别害怕长名称。长而具有描述性的名称，要比短而令人费解的名称好。长而具有描述性的名称，要比描述性的长注释好。使用某种命名约定，让函数名称中的多个单词容易阅读，然后使用这些单词给函数取个能说清其功用的名称
• 函数参数
  • 最理想的参数数量是零（零参数函数），其次是一（单参数函数），再次是二（双参数函数），尽量避免三（三参数函数）。有足够特殊的理由才能用三个以上参数（多参函数）。（多个参数会增加编写测试用例的难度）
  • 如果函数看来需要两个、三个或三个以上参数，就说明其中一些参数应该封装成类了。（封装部分参数，还得一定要让读者明白需要哪些参数，(╯°Д°)╯︵┻━┻）
• 无副作用
  • 函数承诺只做一件事。
• 分隔指令与询问
  • 函数做什么事，回答什么事，是两个操作，应该分开来处理。
• 使用异常替代返回错误码
  • 从指令式函数返回错误码轻微违反了指令与询问分隔的规则。（就是要多try，不过本人在实际工作中都是使用返回错误码或记录日志来处理异常的）
  • 抽离Try/Catch代码块，把try和catch代码块的主体部分抽离出来，另外形成函数。
  • 错误处理就是一件事。函数应该只做一件事。
  • error.java依赖磁铁。返回错误码通常暗示某处有个类或是枚举，定义了所有错误码。
• 别重复自己
• 结构化编程
  • 只要函数保持短小，偶尔出现return、break或continue语句没有坏处，甚至还比单入单出原则更具有表达力。另一方面，goto只在大函数中才有道理。所以应该尽量避免使用。（关于goto的争议蛮大的，我是不建议使用）

注释

• 注释不能美化糟糕的代码
  • 带有少量注释的整洁而有表达力的代码，要比带有大量注释的零碎而复杂的代码像样得多。与其花时间编写解释你搞出的糟糕的代码的注释，不如花时间清洁那堆糟糕的代码。
• 用代码来阐述
  • 很多时候，只需要创建一个描述与注释所言同一事物的函数即可。

　　改前：

// Check to see if the employee is eligible for full benefits
if ((employee.flags & HOURLY_FLAG)) && (employee.age > 65))

　　改后：

if (employee.isEligibleForFullBenfits())

• 好注释
  • 法律信息
  • 提供信息的注释
  • 对意图的解释。（提供了有关实现的有用信息，而且还提供了某个决定后面的意图）
  • 阐释
  • 警示
  • TODO注释。TODO是一种程序员认为应该做，但由于某些原因目前还没做的工作。（这个很常用，但是要定期查看，删除不再需要的）
  • 放大。注释可以用来放大某种看来不合理之物的重要性。
  • 公共API中的javadoc
• 坏注释
  • 喃喃自语。如果只是因为你觉得应该或者因为过程需要就添加注释，那就是无谓之举。如果你决定写注释，就要花必要的时间确保写出最好的注释。
  • 多余的注释
  • 误导性注释
  • 循规式注释
  • 日志式注释（在代码头部注释代码修改记录，书中不建议，现在也很少有这种注释，都用版本控制软件了）
  • 废话注释
  • 能用函数或变量时就别用注释
  • 位置标记。尽量少用标记栏，只在特别有价值的时候用。
  • 括号后面的注释
  • 归属与署名（使用版本控制软件就好了）
  • 注释掉的代码。（书中倡导，反正有管理软件能够找回，所以，不要了，就删掉！）
  • HTML注释（这个还真遇到过，这种注释用于生成API文档用的，在代码中看起来很乱）
  • 非本地信息。假如你一定要写注释，请确保它描述了离它最近的代码。别在本地注释的上下文环境中给出系统级的信息。
  • 信息过多
  • 不明显的联系
  • 函数头。短函数不需要太多描述。为只做一件事的短函数选个好名字，通常要比写函数头注释要好。
  • 非公共代码中的 javadoc