理念

此列表包括项目应遵守的一般精神。此列表并不全面。其中一些是显而易见的，但为了完整性而说明。

¥This list includes general ethos that the project should abide by. This list is not comprehensive. Some of these are obvious but are stated for completeness.

项目管理

Section titled 项目管理

¥Project Management

• 设定明确的期望。提前让项目意图和决策为人所知。没有什么是令人惊讶的。

  ¥Set clear expectations. Make project intent and decisions known well in advance. Nothing should be a surprise.

• 清晰的决策信息。团队可能会使用私有渠道评估选项并做出决定。团队将尝试使用 GitHub 讨论 或 Discord 等公共渠道进行讨论。可能会发生频繁的私有签到。当通过私有渠道做出决定时，团队必须承诺使用公共渠道传达这些决定。

  ¥Clear messaging of decisions. The team might evaluate options and make decisions using private channels. Team will try to keep discussions using public channels like GitHub discussions or Discord. Frequent private check-ins might happen. When decisions occur via private channels, the team has to commit to communicate these decisions using the public channels.

技术

Section titled 技术

¥Technical

• 错误应尽可能建议修复和提示。这些应该从使用中推断和过滤，以减少出现无关紧要和无用的消息。

  ¥Errors should suggest fixes and hints where possible. These should be inferred and filtered from usage to reduce surfacing irrelevant and unhelpful messages.

• 唯一且特定的错误消息。没有通用错误消息。这有助于用户了解出了什么问题，并为维护人员提供唯一的调用站点和调试所需的信息。

  ¥Unique and specific error messages. No generic error messages. This helps users understand what went wrong and should provide maintainers with a unique call site and the necessary information to debug.

• 优化 API。质疑所有选项和标志的存在。它们是必要的吗？它们可以组合吗？我们如何减少代码分支？

  ¥Optimise API. Question the existence of all options and flags. Are they necessary? Can they be combined? How can we reduce code branching?

• 文档代码。尽量为代码提供尽可能多的文档，尤其是 “hard-to-read” 代码，或者需要解释的特殊逻辑。记录良好的代码有助于提高其可维护性，尤其是当多人处理它时。你之后的开发者将从你的知识中受益，分享它。

  ¥Document Code. Strive to document the code as much as possible, especially the “hard-to-read” code, or for special logic that requires explanation. A well documented code helps its maintainability, especially when multiple people work on it. The developer after you will benefit from your knowledge, share it.

• 减少行话。不要假设用户会理解特定的术语。尽量为专家和初学者提供精确的含义。例如，在产生解析器错误时，在传统上使用 “token” 的地方使用 “character”。

  ¥Reduce jargon. Don’t assume that users will understand specific terminology. Strive to provide precise meaning for experts and beginners. For example, use “character” where you would traditionally use “token” when producing parser errors.

• 命名命令和标志时使用详细程度。没有不必要和令人困惑的缩写。

  ¥Utilize verbosity when naming commands and flags. No unnecessary and confusing abbreviations.

• 使用包容性术语。使用中性代词。没有残疾歧视诽谤。不使用可能被认为不敏感的术语。

  ¥Use inclusive terminology. Use gender-neutral pronouns. No ableist slurs. No usage of terms that could be considered insensitive.

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

  ¥Build for generic clients. Don’t assume that a terminal will only consume output using ANSI codes. Use abstractions that could be generalized for viewing in an IDE, browser, or other environments.

• 终端输出应该明确。设计终端输出时，不要纯粹依赖颜色等格式提示。始终使用格式、符号和间距的组合。如果删除所有 ANSI 代码，则仍应理解所有输出。

  ¥Terminal output should be unambiguous. When designing terminal output, don’t rely purely on formatting cues like color. Always use a combination of formatting, symbols, and spacing. If all ANSI codes are stripped, all the output should still be understood.