审阅清单

向 Mozilla 源代码提交补丁不必复杂。本文提供了一份关于补丁内容的最佳实践清单，审阅者会检查或要求满足这些最佳实践。遵循这些最佳实践将使审查和接受过程更加顺畅和快速。

良好的网络公民意识

  • 确保新的 Web 公开 API 确实有意义，并且要么是标准跟踪，要么默认情况下已禁用。

  • 在 C++ 中，根据需要使用包装器缓存。如果您的对象可以从某个地方获取而无需在进程中创建它，则需要对其进行包装器缓存。

正确性

  • 要修复的错误是一个有效的错误，并且应该得到修复。

  • 补丁修复了问题。

  • 补丁不会不必要地复杂化。

  • 补丁不会添加现有代码的重复部分（“几乎重复”可能意味着需要重构）。通常，这会导致错误的“第 0 部分”，即“整理代码以使修复更容易编写和审查”。

  • 如果 QA 需要验证修复，则应提供重现步骤 (STR)。

质量

  • 如果可以对其进行单元测试，则应进行单元测试。

  • 如果是 JS，请尝试设计和构建，以便 xpcshell 可以执行大部分功能。它更快。

  • 确保补丁不会创建任何未使用的代码（例如，在删除功能时删除字符串）

  • 所有捕获的异常都应记录在适当的级别，请记住个人可识别信息，但也考虑到计算和记录日志输出的成本。[Fennec：除非您使用 Logger，否则检查日志级别会很昂贵。]

风格

  • 遵循所讨论语言和模块的样式指南。

  • 遵循周围代码的本地样式，即使该本地样式没有正式记录。

  • 新文件具有许可证声明和模型行。

  • 新的 JS 文件应使用严格模式。

  • 尾随空格（git diff 和 splinter 视图都突出显示了这一点，启用颜色扩展的 hg 也是如此）。可以使用 Mercurial 中的CheckFiles 扩展轻松修复空格。在 git 中，可以使用 git rebase –whitespace=fix。

安全问题

  • 不应向配置文件文件夹之外的任意文件写入数据。

  • 读取用户输入、网络输入或磁盘上的文件时要小心。假设输入将过大、过短、为空、格式错误或具有恶意意图。

  • 如果不确定，请标记为安全审查。

  • 如果您正在编写使用 JSAPI 的代码，则很可能出错。尽量避免这样做。

隐私问题

  • 不应记录 URL 或可以推断出 URL 的内容。

  • [Fennec：Android 服务为此目的提供了 Logger.pii()（例如，记录配置文件目录）。]

  • 如果需要，请标记为隐私审查。

资源泄漏

  • 在 Java 中，内存泄漏主要是由于单例持有缓存和集合，或观察者持续存在，或 Runnable 停留在队列中。

  • 在 C++ 中，根据需要进行循环收集。如果 JavaScript 可以看到您的对象，则可能需要对其进行循环收集。

  • [Fennec：如果您的自定义视图执行动画，最好在 onDetachFromWindow() 中清理 Runnable。]

  • 确保所有文件句柄和其他可关闭资源都已正确关闭。

  • [Fennec：在编写使用 PaintedSurface 的测试时，确保在完成使用后关闭 PaintedSurface。]

性能影响

  • 检查主线程 IO [Fennec：Android 可能会使用 strictmode 警告此问题]。

  • 删除生产环境中不需要的调试日志。

线程问题

  • 非常重要：正确使用锁定和易失性；活锁和死锁；所有权。

  • [Fennec：所有视图方法都应仅在 UI 线程上访问。]

  • [Fennec：活动生命周期感知（与“从不保留活动”一起使用）。还应使用 oom-fennec 进行测试 (https://hg.mozilla.org/users/blassey_mozilla.com/oom-fennec/)。]

兼容性

  • 版本文件、数据库、消息

  • 使用 ID 标记消息以区分调用者。

  • 更新接口时更新 IDL UUID。

  • Android 权限应“分组”到一个公共版本中，以避免破坏自动更新。

  • 自 Froyo 以来添加的 Android API 应受版本检查保护。

可配置性

  • 如果正在处理的功能受首选项控制，请确保它们已连接。

  • 如果正在处理新功能，请考虑添加首选项以控制行为。

  • 考虑添加首选项以在发布周期后期发现错误时完全禁用该功能。

  • [Fennec：“首选项”可以是 Gecko 首选项、SharedPreferences 值或构建时标志。选择哪一个取决于功能的实现方式：例如，纯 Java 服务不容易检查 Gecko 首选项。]

字符串

  • 在将要提升的补丁中不应进行任何字符串更改（包括字符串删除）。

  • 更改字符串时修改实体名称。

  • 进行 UI 更改时，请注意字符串在不同语言环境中的长度将不同。

文档

  • 提交消息应描述补丁正在更改的内容（而不是复制错误摘要）。第一行应为简短描述（因为日志中仅显示第一行），如果需要，其他描述应在后续行中以正确的格式显示。

  • 充分记录任何可能令人困惑的代码部分。

  • 如果任何附加组件或 Web API 受影响，则使用 dev-doc-needed 标记错误。

  • 广泛使用 Javadoc，尤其是在任何新的非私有方法上。

  • 移动文件时，确保保留 blame/annotate 信息。

可访问性

  • 对于 HTML 页面，图像应在适当情况下设置 alt 属性。类似地，不是原生 HTML 按钮的按钮应具有 role="button" 和 aria-label 属性。

  • [Fennec：确保为 UI 中应可访问的部分设置 contentDescription]