以人为本审查代码

Source: Dev.to

我的一个强项是能发现别人代码中的问题 😜。下面是我在审查 PR 时使用的检查清单。虽然像 Copilot 这样的 AI 工具可以提供帮助，但它们仍然会错过需要人工判断的细微差别。

可重用性

重复的逻辑

• 逻辑是否可以提取为可重用的组件或函数？
• 提取的代码是否已得到充分测试，以便在无需重新编写或重新测试的情况下重复使用？
• 在一个地方更新逻辑应自动传播到所有使用处，减少因实现不一致导致的错误。

硬编码的、重复的值

• 将此类值存储为共享文件中的常量。
• 使用常量可减少拼写错误，并使未来的更改只需在单一点进行编辑。
• 现代 IDE 能自动补全已导入的常量，进一步降低错误率。

可测试性

• 之前通过的测试是否开始失败或需要更改？
  • 失败的测试可能表明出现了意外的修改、拼写错误或副作用。
  • 首先验证实现本身；不要仅仅“修复测试”。
  • 仔细检查差异，留意缺失的括号、拼写错误或细微的逻辑更改。

可读性 / 可理解性

命名

• 名称应描述组件、文件、变量或函数的作用。
  • 例如：一个表示按钮是否应显示的布尔值可以命名为 isButtonVisible。
  • 清晰的名称减少额外注释的需求，帮助人类和 AI 理解代码。

复杂逻辑

• if/else 语句太多？
  • 考虑使用 switch 语句或将其重构为更小的辅助函数。

函数参数

• 参数太多？
  • 使用带命名属性的单个对象来传递，而不是长位置参数列表。
  • 这可以避免顺序错误，并让可选参数更清晰。

注释 & 业务逻辑

• 如果代码难以跟踪，添加注释解释底层业务规则。
• 重要的逻辑还应通过单元测试和端到端测试进行覆盖。

安全

即使使用静态分析，也可能会漏掉一些不安全的模式。

• 永不信任用户输入 – 在将原始输入发送到服务器或在浏览器中渲染之前进行清理（防止 XSS）。
• 保护个人身份信息（PII） – 在将个人身份信息发送给第三方服务之前进行掩码或加密。
• 避免泄露机密 – 确保 API 令牌、机密信息和 .env 文件未被提交。立即轮换任何已泄露的凭证。

错误处理

• 处理预期错误 – 将网络请求（例如 fetch）包装在 try/catch 块中。
• 避免意外变更 – 在修改对象之前进行克隆，或使用返回只读值的 getter。
• 面向用户的错误信息 – 不要暴露堆栈跟踪、服务器细节或其他可能帮助攻击者的敏感信息。

类型安全

• 确保所有数据，尤其是 API 响应，均使用正确的类型（例如，使用 TypeScript 接口或类型）。
• 明确定义的类型可以提前捕获不匹配，并使代码库更易于维护。

摘要

在彻底性与实用性之间取得平衡是关键。人类判断让我们能够决定什么是“足够好”，什么需要更深入的审查——这是仅靠 AI 无法完全复制的。将此检查清单视为活文档；随着团队和代码库的演变进行调整。

避免错误

这样可以降低错误的可能性。例如，你可以在将键的值转换为大写之前，先检查该键是否具有特定名称。如果键名输入错误，代码将无法按预期工作。

另一个问题是字段是可选的；如果你不知道它是可选的，可能会跳过检查它是否已定义，从而在缺失时导致运行时错误。定义接口可以让你的 IDE 帮助你识别准确的键名，避免因错误假设而产生的失误。

优化

我也会寻找可以优化代码行数的地方。更少的代码行通常意味着更少的错误机会。

• 在某些情况下，你可以检查是否已经有具有相似逻辑的工具函数可以复用。寻找方法来改编或稍作扩展该工具函数，使其能够支持新的实现。
• 你真的需要分配中间变量吗？如果可以直接使用对象映射或链式调用就不必。额外的变量会占用更多内存——虽然单独来看通常可以忽略不计，但此类细微的改动累积起来可以提升性能。

我确信在 PR 中我还会关注其他方面，但这些是我目前能想到的最重要的点。重要的是你要关心产品、应用的用户、自己以及你的团队成员。如果你足够在乎，你会注意到代码中的大多数错误并尝试修复它们。这正是我们作为人工审阅者的独特之处。