理念

我们对构建 Biome 的思考方式。

以下列出项目应当遵循的一般原则。 这份清单并不详尽。有些内容不言自明，但为了完整性仍在此列出。

项目管理

• 设定清晰的预期。 尽早让外界知晓项目的意图与决策。 不应有任何令人意外的事情。

• 公开同步决策。 团队可能通过私有渠道评估方案并做出决策。 团队会尽量把讨论保持在 GitHub discussions 或 Discord 等公开渠道。私下的例行沟通可能会出现。 一旦决策是通过私有渠道做出的，团队必须承诺通过公开渠道同步这些决策。

技术

• 错误信息应尽最大可能给出修复建议和提示。 这些建议应从实际使用中推断并过滤，避免呈现无关且无帮助的消息。

• 错误信息要独一无二且足够具体。 不要使用泛化的错误信息。 这能帮助用户理解出了什么问题，也能为维护者提供唯一的调用点以及调试所需的信息。

• 优化 API。 质疑每一个选项与选项存在的必要性。 它们是否必要？能否合并？如何减少代码分支？

• 编写代码文档。 尽可能为代码补充文档，尤其是那些「难读」的代码，或需要额外解释的特殊逻辑。 文档完善的代码更利于维护，多人协作时尤其如此。你之后的开发者会从你的知识中受益，请把它分享出来。

• 减少行话。 不要假设用户能理解特定的术语。 无论面向专家还是新手，都要努力给出精确的含义。 例如，输出解析器错误时，用 "character" 一词替代传统上的 "token"。

• 命令与选项的命名要完整清晰。 不要使用多余且令人困惑的缩写。

• 使用包容性术语。 使用性别中立的代词。不要使用针对残障人士的侮辱性用语。 不要使用可能被视为不敏感的词汇。

• 面向通用客户端构建。 不要假设终端只会通过 ANSI 代码消费输出。 使用可以泛化到 IDE、浏览器或其他环境中查看的抽象。

• 终端输出不得含糊。 设计终端输出时，不要只依赖颜色这类格式线索。 始终组合使用格式、符号与空白。 即使剥离所有 ANSI 代码，全部输出仍应可以被理解。