以尊重的态度编码

包容性是 Android 文化的核心,我们的价值观也倡导相互尊重。因此,每个人都应在没有偏见和歧视的环境中贡献代码。但是,我们的代码库、界面和文档中所用的术语可能长期存在这种歧视。以下政策就如何在代码、界面和文档中避免使用不当术语提供了相关指导。

政策

应避免使用直接或间接诋毁、伤害或歧视他人的术语。这一点与 Google 的包容性文档编写指南一致。

该政策的适用范围

Android 代码贡献者会看到的任何内容,包括但不限于:

  • 变量、类型、函数、文件、构建规则、二进制文件及导出变量的名称
  • 测试数据
  • 系统输出和显示内容
  • 注释和文档(源代码文件内外)
  • 提交说明

原则

  • 尊重他人:介绍运作方式时不应使用诋毁性语言。
  • 使用在文化上合宜的语言:某些字词可能具有重要的历史意义或政治意义。请注意这个问题并使用替代字词。

如何判断特定术语是否使用得当?

以上述原则为准。如有任何疑问,请发送电子邮件至 android-community@googlegroups.com

应避免使用的术语示例有哪些?

以下列表并不全面,仅包含大家经常会遇到的一些示例。

请注意,注释是否值得添加始终要认真考虑。 有时,最好的解决办法就是彻底移除注释。例如,即使您要为公共 API 编写文档注释,在即将调用 verify_header 函数之前仅添加注释“Sanity check the header”也没有任何价值,而要具体说明所检查的内容,例如“Check header for out of range values”。

术语 建议使用的替代术语
主/从 主本/副本、主要/次要、领导者/跟随者、控制器/分配器、管理器/工作器、混合器/分离器、聚合器/收集器、发布者/订阅者、发起者/响应者
红线 优先级线、跟踪更改、设计规范、界面注释、例外情况、异常情况、特殊情况、替换列表
白名单 许可名单、许可列表、包含列表、安全列表
黑名单 拒绝列表、屏蔽列表、排除列表、屏蔽名单
(深|浅)灰名单 对于 API:
  • (灰名单)“非 SDK API 列表”、“隐藏的 API 列表”
  • (深灰名单)“有条件地屏蔽”或在指特定列表时使用 max-target-X
  • (浅灰名单)“不建议”、“临时性”
疯狂、疯子、残废 如需了解相关指南,请参阅避免使用残障歧视语言
健全性检查 仅用“检查”一词传达不出意思的差别。请视不同情况考虑使用验证、快速检查、初始检查、置信度检查、可靠性检查、校准检查、就绪性检查。
哑字符 未使用、占位符、空操作、基字符、假/模拟/桩
祖父原则 豁免、现有、延续、沿用、基准、旧版
性别代词(例如,他或她) 他们、他们的
中间人 (MITM) 路径攻击者
(黑|白|灰|)帽 道德/不道德
一等公民 核心功能、内置、顶级

如果我发现某些内容违反了该政策,该怎么办?

这种情况出现过几次,特别是在代码实现规范中。在这些情况下,与规范中的语言不同可能会影响用户对实现的理解,我们建议采用以下方法中的一种(按偏好降序排序):

  1. 如果使用替代术语不影响用户理解,请使用替代术语。
  2. 请勿在执行交互的代码层以外传播术语。如有必要,请在 API 边界使用替代术语。
  3. 如果您无法自行修改语言,请向相关团队提交错误