读《代码整洁之道》

简评

整洁代码的重要性

糟糕的代码毁了公司

混乱的代价

读与写花费时间的比例超过 10 : 1

稍后等于永不

必须时时保持代码整洁

随时随地重构垃圾代码是我立即学会的事情并进行实践的事情，推荐大家也立即行动起来。 稍后等于永不，其实和《搞定Ⅰ 无压工作的艺术》中讲的一样，一件小事如果能立即完成，就立刻完成它，而不是稍后在做。喝完牛奶就洗杯子，吃完饭就洗碗，别让这些小事拖垮自己。

有意义的命名

名副其实

做有意义的区分

1. 别用什么 a1, a2 作为变量命名（当心被砍）。

2. 不要用什么 ArrayList 作为命名，既然有 List 了，为什么还要用 Array 呢？

// 他们有什么区别吗？
getActiveAccount();
getActiveAccounts();
getActiveAccountInfo();

// 直接用这个就可以
getActiveAccount();

使用读得出来的名称

方法名用动词

添加有意义的语境

不要添加没用的语境

命名是一件很重要的事情，好的命名能让代码可读性提升 100%！ 能用命名解决的事情，就不要再加注释了。

函数

短小

只做一件事

单一权责原则

使用描述性的名称

函数参数

1. 最理想的参数数量是零：过多的参数测试用例就很难写，因为把所有参数的组合搞出来就是一件痛苦的事情。一般来说参数数量越少的代码越容易理解；

2. 标识参数：标识参数指的就是 Bool 类型的参数，使用 Bool 参数就明显代表了这个 fun 在做两种事情，所以这个时候我们应该把他们拆开！

3. 参数对象：如果函数看来需要两个、三个或三个以上参数，就说明其中一些参数应该封装为类了；
1. 看起来像作弊，但其实并不是；
2. 因为参数对象有着自己的定义，例如我传的是 goods 商品信息，那么它的定义就是商品信息，就是一个整体，我在使用的时候也知道 goods 是个什么东西；

无副作用

使用异常替代返回错误码

如何写出这样的函数

注释

注释不能美化糟糕的代码

用代码来阐述

好注释

1. 提供信息的注释：例如：这个函数被用在什么地方等等

2. 对意图的解释：例如：为什么这部分代码一定要放在这个位置

3. 警示：这串代码别乱动，因为 xxx 原因，这个在代码库里挺常见的，哈哈~

4. 其他的还有：法律信息、TODO、API 注释

坏注释

1. 喃喃自语的废话、多余的注释（还不如看代码，扰乱读者）

2. 误导性的注释：通常是代码逻辑发生变更，而注释并没有一起变动
1. 这就是为什么能不用注释尽量不要用注释，代码永远是有效的，而注释不是

3. 日志式注释、归属与署名：
1. 很久以前，在模块开始处创建并维护这些记录还算有道理。那时，我们还没有源代码控制系统可用。如今，这种冗长的记录只会让模块变得凌乱不堪，应当全部删除。

4. 可怕的废话：

interface Person {
  // 名称
  name: string
  // 年龄
  age: number
  // 性别
  male: boolean
}

5. 能用函数或变量名称描述时时就别用注释

6. 注释掉的代码：没用的代码就删了吧，有 Git 帮你存呢，再说留着真的有参考意义吗？

7. 信息过多：注释里面加了太多的废话或者无关的细节描述

如果你发现自己需要写注释，再想想看是否有办法翻盘，用代码来表达。每次用代码表达，你都该夸奖一下自己。每次写注释，你都该做个鬼脸，感受自己在表达能力上的失败。

代码格式

垂直格式

横向格式

团队规则

错误处理

使用异常而非返回码

给出异常发生的环境说明

整洁代码是可读的，但也要强固。可读与强固并不冲突。如果将错误处理隔离看待，独立于主要逻辑修就能得出强国面整洁代码。

单元测试

TDD 三定律

1. 在编写不能通过的单元测试前，不可编写生产代码

2. 只可编写刚好无法通过的单元测试，不能编译也算不过

3. 只可编写刚好足以通过当前失败测试的生产代码

保持测试整洁

1. 可读性：看不懂的测试用例和看不懂的代码一样恐怖；

2. 构造-操作-检验(BUILD-OPERATE-CHECK)模式：就按照这个流程写测试用例，让读测试的人可以快速明白测试 case 的做什么；

3. 打造了一套包装这些API的函数和工具代码：通过封装工具代码，让编写测试变得简单；

每个测试一个断言

F.I.R.S.T 原则

1. 快速(Fast)
1. 测试应该够快。测试应该能快速运行。测试运行缓慢，你就不会想要频繁地运行它。如果你不频繁运行测试，就不能尽早发现问题，也无法轻易修正，从而也不能轻而易举地清理代码。最终，代码就会腐坏。

2. 独立(Independent)
1. 测试应该相互独立。某个测试不应为下一个测试设定条件。你应该可以单独运行每个测试，及以任何顺序运行测试。当测试互相依赖时，头一个没通过就会导致一连串的测试失败，使问题诊断变得困难，隐藏了下级错误。

3. 可重复(Repeatable)
1. 测试应当可在任何环境中重复通过。你应该能够在生产环境、质检环境中运行测试，也能够在无网络的列车上用笔记本电脑运行测试。如果测试不能在任意环境中重复，你就总会有个解释其失败的接口。当环境条件不具备时，你也会无法运行测试。

4. 自足验证(Self-Validating)
1. 测试应该有布尔值输出。无论是通过或失败，你不应该查看日志文件来确认测试是否通过。你不应该手工对比两个不同文本文件来确认测试是否通过。如果测试不能自足验证，对失败的判断就会变得依赖主观，而运行测试也需要更长的手工操作时间。

5. 及时(Timely)
1. 测试应及时编写。单元测试应该恰好在使其通过的生产代码之前编写。如果在编写生产代码之后编写测试，你会发现生产代码难以测试。你可能会认为某些生产代码本身难以测试。你可能不会去设计可测试的代码。

味道与启发

注释

1. 不恰当的信息：别传达和代码无关的多余信息，例如修改历史记录（Git 会帮你记录）

2. 废弃的注释：尽快删除

3. 冗余注释：看注释不如看代码

4. 糟糕的注释：要写注释就好好写，别写看不懂、难读的注释

5. 注释掉的代码
1. 污染模块、分散读者注意力
2. 注释掉基本上就是废弃代码了，直接删除就可以，如果真的需要，看之前版本就可以

环境

1. 需要多步才能实现的构建
1. 系统应该能够使用一个命令进行构建

2. 需要多步才能做到的测试
1. 一行命令运行所有测试

一般性问题

1. 明显的行为未被实现：指的是函数名称所描述的行为，函数并没有实现，这就导致其他程序员不再信任函数名称

2. 不正确的边界行为：每种边界条件在我们编码的时候都需要考虑到，而不是依赖直觉，“感觉没问题” 不代表没问题

// ❌错误
async function f() {
  const a = await getA();
  const b = await getB();
  return c;
}

// ✅正确
async function f() {
  try {
    const a = await getA();
    const b = await getB();
    return a + b;
  } catch (e) {
    // do something
  }
}

3. 忽视安全：请务必遵守各种 SOP

4. 重复：
1. 每次看到重复代码，都代表遗漏了抽象
2. 尽量不要复制粘贴代码，能做好抽象就做好抽象

5. 信息过多：设计良好的模块有着非常小的接口，让你能事半功倍

6. 死代码：请务必删除废弃代码

7. 人为耦合：不互相依赖的东西不该耦合

8. 晦涩的意图：这点我认为很重要，代码如果为了追求简短写的晦涩难懂，不如写长一些，可读性高一些

9. 使用解释性变量：良好的命名很重要

10. 函数名称应该表达其行为：
1. getUserList 这个命名代表了获取用户列表，那么除了获取用户列表不要做别的任何事情！

11. 理解算法：算法 > 无数 if

12. 遵循标准约定：遵守团队定义的代码规则

13. 用命名常量替代魔术数
1. 不是所有情况都需要使用常量代替
2. 如果魔术字很有强的自我解释能力，例如 2 圈，同时没有在多个地方进行使用，那么就可以直接使用魔术字

14. 准确：在代码中做决定时，确认自己足够准确

15. 避免否定性条件
1. if (buffer.shouldCompact()) 要好于 if (!buffer.shouldNotCompact())

16. 函数只该做一件事

17. 掩蔽时序耦合
1. 当有时许耦合时，如何正确处理，请让后面的函数接收前面的参数

名称

1. 采用描述性名称
1. 不要太快（太随意）取名，认真思考应该取什么名称，确认名称具有描述性

2. 无歧义的名称
1. 名称很像的时候就会发生混淆，所以我们取名的时候需要避免这种情况

3. 为较大作用范围选用较长名称
1. 可以理解为，我们在简单的 for 循环里面使用 key, value 这种命名，但是作用范围变大后，这种命名就不太合适了

4. 名称应该说明副作用，而不是悄默默的添加副作用