代码注释
在当前任务范围内维护帮助读者定位、调用和修改代码的说明。优先让命名和结构表达意图；仍有信息缺口时补充注释，无需为每个声明添加说明。
原则
接口优先：优先检查模块向调用者提供接口的接缝，让调用者无需阅读实现即可正确使用。补充名称和类型未充分表达的业务含义、前置条件、副作用或失败后的状态等约定。
结构化说明：模块与接口文档采用项目语言和工具链支持的格式，如 TSDoc、Javadoc，并放在对应声明处。摘要简短，标签按需使用，避免重复类型签名或机械填写空泛说明。
便于检索：在承担相应职责的入口自然使用项目统一的领域术语。让需求中的用词能够定位到实现，避免堆叠关键词或在各处重复同一段说明。
实现理由：实现注释优先解释为什么这样做、需要保留哪些约束，避免复述代码已清楚表达的操作。局部理由使用普通注释，放在相关代码旁；无法确认的设计理由不写成事实。
自包含：必要约定和实现理由直接写在源码中，避免让读者依赖代码外的文档，尤其是未纳入版本管理的资料。共同约定集中在权威接口处，各实现通过代码符号引用或文档继承复用，只补充自身特有的信息。
随代码更新：行为变化时同步修正受影响的注释，删除已确认失真或冗余的说明。以是否提供必要信息判断价值，不追求注释数量或覆盖率；日常改动不扩展为全仓补注释。