软件开发中的命名、注释和文档是否应当尽量使用英语？

建议代码标识符和对外技术接口默认使用英语，注释与文档则根据读者选择语言。长期由本地团队维护的内部项目，也可以用团队熟悉的语言编写说明。仅凭“没有使用英语”，不能认定项目存在严重工程错误。

原问题没有提供具体项目案例或维护数据，无法据此判断非英语项目通常会增加多少成本。

为什么英语适合作为默认选择？

软件可能比预期存活得更久，也可能交给其他国家或地区的团队维护。制定规范时需要考虑这种情况：如果后来需要跨语言协作，已有的命名、注释和设计说明都会影响交接。

采用英语通常有几项实际便利：

• 自定义名称更容易与所用 API、库和技术资料中的英语术语保持一致。
• 当协作者共同掌握英语时，可以减少理解代码所需的翻译工作。
• 对外提供 SDK、公共 API 或开放源码时，更容易让预期读者理解接口。

这些便利有适用条件：团队成员需要理解所用的英语，名称也必须准确。拼写正确但含义模糊的英语，仍然可能造成维护困难。

本地项目能否使用本地语言？

可以，但要分别考虑代码、内部说明和用户文档。

本地用户的语言主要决定界面、帮助文档和业务材料的语言，不能直接决定代码标识符的语言。如果维护人员都使用同一种本地语言，详细的业务规则和设计理由用该语言表达，可能更准确，也更方便评审。

如果项目明确限定在本地团队，使用本地语言是可以接受的。应把这一约定写清楚，并在团队构成或项目用途变化时重新评估。

英语不熟练时，怎样避免命名和注释失真？

先约定术语，再要求统一语言。如果每位开发者各自翻译同一个业务概念，很容易出现多个近义名称，也可能把两个不同概念翻成同一个词。

可以从以下步骤开始：

1. 建立小型术语表，记录业务概念、采用的代码名称、含义和容易混淆的概念。
2. 采用简单、明确的表达。名称说明对象或行为，注释解释约束和原因，不追求复杂句式。
3. 在评审中检查含义，确认名称与实际行为一致，尤其注意否定条件、范围和状态含义。
4. 保留必要的领域原词。对没有准确英语对应词的概念，可以约定保留原词并补充定义，避免勉强翻译造成误解。

下面是一个示意例子，并非原问题中的代码：

def has_active_users(users):
    # 停用用户不计入判断；这里只检查是否存在启用用户。
    return any(user.is_active for user in users)

has_active_users 表达了返回值是在判断“是否存在启用用户”，注释则说明判断范围。是否把注释改成英语，应由维护者的阅读需求决定。无论用哪种语言，都不能把“存在一个”误写成“所有用户”。

已有非英语项目，需要整体翻译吗？

通常不宜仅为统一语言就进行全量改名。应先判断当前是否存在实际阅读障碍，以及哪些内容影响协作和交接。

可以按以下顺序推进：

1. 明确当前维护者和预期接手者能够使用的语言。
2. 优先处理他们必须阅读的入口说明、构建步骤、关键设计和接口文档。
3. 为新增代码制定规范，修改旧代码时逐步统一术语。
4. 对公共名称单独评估兼容性，确认调用方和相关文档都能同步调整。

还要区分“代码内部名称”和“外部可见名称”。字段名可能已经进入 JSON、数据库、配置文件或第三方接口；修改它们可能改变使用约定，不能只按普通重构处理。

如果保留双语文档，应明确哪一份是主要维护版本，以及由谁同步更新。两份内容长期不一致，会让读者无法判断哪一份可信。

如何制定适合团队的规范？

对没有特殊约束的新项目，可以采用这样的起点：标识符默认使用英语，业务术语统一约定；公共技术资料按协作者的语言需求提供；内部注释和详细说明允许使用团队表达最准确的语言。

评估规范是否合适，要看新成员能否理解、术语是否一致、关键规则能否准确表达，以及资料是否有人持续维护。未来可能国际化，可以作为优先使用英语的理由；制定规范时也要考虑当前团队的表达能力及相应的维护成本。

备注：内容仅供参考。