每日PR保持代码整洁自查表
原创大约 4 分钟
每日PR保持代码整洁自查表
如今，公司对软件工程师（主要是高级工程师）最迫切的需求之一，是以迭代和增量的方式提供高质量的代码审查。
这意味着在每次 PR 审查中，开发人员被要求反复提高即将合并代码的质量。
在这篇文章中，我将尝试指出开发人员在进行重构或审查时应牢记的基本原则。
让我们逐个主题来看这些点：
1. 命名
- 有明确意图的命名：方法或变量名应该在查看代码实现之前就能解释其意图。
- 类名应该是名词或名词短语。
- 方法名应该是动词。
- 为每个概念选择一个词：get、retrieve、fetch 是相似的，选择一个统一使用它。
- 使用计算机科学术语：例如，AccountAdapter 对程序员来说意味着适配器模式，如果没有相关的计算机科学名称，则使用面向问题的名称。
- 使用可搜索的名称：在 IDE 中搜索特定短语会更容易。
2. 函数
- 函数应该小：函数越大，调试起来就越困难。
- 块和缩进应该整洁：用好 IDE 的代码格式化。
- 只做一件事：一个函数意味着一个任务。
- 每个函数一个抽象层次：函数应该足够小，以便在一个抽象层次的范围内实现。
- 从上到下阅读代码：应该应用逐步下降规则。嵌套函数应该在母函数之后，以便有像阅读书籍一样的感觉。
- 使用较少的输入：超过 3 个输入则很糟糕，这可能意味着函数在做不止一件事。
- 没有副作用：函数应该只做一件事，并且应该正确地做这件事，而不对其他状态产生不良影响。
- 没有重复：将频繁使用的代码片段集中在一个地方。
3. 注释
- 尽量用代码表达意图：你的代码应该是自解释的，以至于读者不需要额外的注释。
- 好的注释：
- 法律注释
- 信息性注释
- 澄清晦涩的代码
- 警告后果
- TODO注释
- 坏的注释：
- 含糊不清
- 冗余注释
- 误导性注释
- 强制性注释
- 日志注释
- 噪音注释
4. 格式化
- 垂直格式化：类的大小最多 200-300 行代码。
- 报纸隐喻：类应该像报纸文章一样。
- 垂直开放性：类中变量/方法之间的垂直距离。
- 变量声明：类变量在构造函数之前，局部变量靠近其使用位置。
- 依赖的方法应该靠近其实现：以便轻松地从一个代码行跳到另一个代码行。
- 水平密度：避免需要滚动的长行。
- 团队规则：团队的一致性比干净的代码更重要。
5. 对象和数据结构
- 数据/对象反对称性：
- 过程式代码（使用数据结构的代码）使得在不改变现有数据结构的情况下添加新函数变得容易。面向对象的代码则使得在不改变现有函数的情况下添加新类变得容易。
- 过程式代码使得添加新数据结构变得困难，因为所有函数都必须改变。面向对象的代码使得添加新函数变得困难，因为所有类都必须改变。
- 迪米特法则：模块不应该知道它操作的对象的内部。
- 数据传输对象：具有公共变量且没有函数的类使得数据传输更容易，但可能存在安全问题。
6. 错误处理
- 尽可能使用异常：而不是返回 null 或错误标志，抛出异常。
- 在异常中提供上下文：尝试制定良好的异常处理策略。
- 不要返回 null，不要传递 null。
7. 单元测试
- TDD 法则：
- 在编写失败的单元测试之前，不允许编写生产代码。
- 不允许编写超过失败所需的单元测试。
- 不允许编写超过通过当前失败的测试所需的生产代码。
- 保持测试干净和可读。
- 每个测试/每个主题/每个概念一个断言。
- 测试应该是 F.I.R.S.T.：
- 快速
- 独立
- 可重复
- 自验证
- 及时
8. 类
- 封装：利用面向对象编程。
- 单一职责原则：每个类应该有一个单一的责任。
- 内聚性：函数操作的变量越多，它的内聚性就越强。
- 应使用极简主义方法。
本文翻译自：https://medium.com/@azeynalli1990/clean-code-cheat-sheet-for-senior-developers-in-daily-pr-reviews-6b77ee413469