样式指南

与其他项目一样,我们也有一些代码规范需要遵守。对于整个远程代理项目,一些大致的规则是

  • 使您的代码可读且合理,不要试图耍聪明。优先选择简单易懂的解决方案,而不是更复杂和陌生的语法。

  • 在进行实际更改时,将修复样式违规作为准备性清理步骤是好的,但在其他情况下,请避免为了符合样式指南而进行无用的代码改动。

  • 代码是可变的,而不是一成不变的。签入的任何代码都不是神圣不可侵犯的,我们鼓励进行更改,使这个生态系统成为一个令人愉快的协作环境。

  • 我们绝不提交任何不必要或未使用的代码。

文档

我们将我们的文档(您正在阅读的文档!)保存在树中,位于 remote/doc。理想情况下,对文档的更新和细微更改不应像代码更改那样受到严格审查,以鼓励频繁更新,防止文档过时。为此,允许任何具有提交访问级别 3 的用户使用 r=me a=doc 更改文档。

使用 fmt(1) 或等效的特定于编辑器的机制(例如 Emacs 中的 Meta-Q)将段落格式化为最多 75 列,目标约为 65 列。这等效于 fmt -w75 -g65,这恰好是 BSD 和 macOS 上的默认设置。

可以这样在本地构建文档

% ./mach doc remote

代码风格检查

远程代理主要由 JavaScript 代码组成,我们使用 mozlint 对其进行代码风格检查,该工具协调了包括 eslint 在内的不同代码风格检查器。

要运行代码风格检查器并为修改的文件获取有意义的输出

% ./mach lint --outgoing --warning

对于某些类型的样式违规,eslint 具有自动修复和格式化代码的模式。这对于保持空格和缩进规则特别有用。

% ./mach lint --outgoing --warning --fix

代码风格检查器也作为 try 任务运行(简写为 ES),这意味着任何样式违规都会自动阻止补丁落地(如果使用 autoland)或导致您的更改集被回退(如果直接落地到 inbound)。

如果您使用 git(1),您可以在推送之前(或提交之前)通过预推送(或预提交)钩子 启用自动代码风格检查。这将在推送之前对已更改的文件运行代码风格检查器,如果存在任何问题,则会中止推送。这对于避免因简单的代码风格检查问题导致 try 运行失败非常方便。