Coding Standards

通用编码标准

技术反模式（危险信号模式）

检测到以下任一模式时，暂停实现并记录：触发的模式、受影响的当前需求、最小的合规替代方案，以及恢复所需的验证。当替代方案消除该模式或有文档记录的需求证明保留该模式合理时，方可恢复。

代码质量反模式

1. 相似代码编写 3 次或以上 —— 违反三次法则（Rule of Three）
2. 单个文件中混杂多种职责 —— 违反单一职责原则（SRP）
3. 在多个文件中定义相同内容 —— 违反 DRY 原则
4. 未检查依赖关系就进行修改 —— 存在意外影响的可能性
5. 用注释禁用代码 —— 应使用版本控制
6. 错误抑制 —— 隐藏问题会形成技术债
7. 用类型断言替代保证 —— 声明了既无运行时检查也无既有契约作为依据的类型

设计反模式

• “暂时能用就行”的思维 —— 技术债的累积
• 补丁式实现 —— 对现有代码进行无计划的追加
• 对不确定技术的乐观实现 —— 假设未知要素“大概能行”就进行设计
• 对症式修复 —— 不解决根本原因的表面修复
• 无计划的大规模变更 —— 缺乏渐进式方法

基本原则

持续排查，直到依据能够确定在保持系统正确性和可维护性的前提下，以最低总复杂度交付所需的用户、运维或维护者价值的方案。

• 基于依据的重构范围 —— 只重构阻碍当前结果、被当前任务变更、或未通过适用质量检查的代码；使用保持行为不变的小步骤。对其他发现，连同其所属边界和依据一并报告，而不扩大当前变更范围
• 仅限当前需求的代码 —— 只有当当前需求、已验证的约束、或有依据支持的实质性风险要求时，才引入新的代码路径、能力、基础设施、抽象或推测性的边缘情况处理（YAGNI）
• 设计收敛 —— 以最小的设计增量交付当前所需的结果。在引入持久状态、公共或跨边界契约、行为模式、可复用抽象或组件拆分之前，先记录现有能力已经交付了什么、它们在当前结果上未能交付什么，以及为什么该新增是能弥合这一差距的最小方案

对每个被激活的层面综合评估总复杂度：用户决策、设置、模式、概念、输出、持久状态和实现路径，以及它们各自在 UX、运行时、实现、测试、文档和维护方面的成本。只比较各可行方案之间存在差异的维度。当能以更低的总复杂度交付相同的已确认价值和验证结果时，优先选择复用或不引入新机制。

注释编写规则

• 代码优先：命名、类型和结构是主要的表达媒介；只有在注释能传达代码无法表达的信息时才添加注释。犹豫不决时，改进命名而不是加注释
• 注释“为什么”，而非“是什么”：解释推理过程、权衡取舍、约束/边缘情况，或公共 API 契约
• 内容不过时：注释包含当前的推理、约束、边缘情况或 API 契约；开发历史由版本控制保留
• 长期有效：只写在任何阅读时刻都依然有效的内容
• 简洁性：将说明控制在必要的最低限度