用途
code-comments 旨在帮助开发者编写与代码共存的注释和文档。其核心主张是：文档应与它所描述的代码放在一起（co-location），因为独立文件中的文档容易与代码脱节，而紧邻代码的注释会随代码一同更新，从而保持准确。
它面向三类读者：半年后的自己、阅读不熟悉代码的团队成员，以及一次只能看到一个文件的 AI 助手（如 Claude、Copilot）。
核心原则
在写注释之前先做“为什么”测试：问自己“这条注释解释了代码为何存在，或为何这样实现吗？”如果只是把代码做的事再说一遍，就应跳过。
写作风格要求：
- 使用平实语言，像在向一位聪明但不了解上下文的同事解释。
- 使用主动语态，例如“This function validates...”，而不是“Validation is performed...”。
- 具体明确，例如“Retries 3 times with 1s backoff”，而不是“Handles retries”。
- 跳过显而易见的内容，例如代码已写 user.isAdmin，就不要注释“checks if user is admin”。
- 对会过期的内容标注日期：临时方案、版本相关代码和临时解决办法应注明何时可以移除。
- 引用常量而非复制数值：当行为由常量控制时，按名称引用常量，不要在注释中重复其值。
关于最后一点，资料给出的示例是：坏做法是“Returns true if stale (not updated in last 5 minutes)”，好做法是“Returns true if stale (not updated within [STALE_THRESHOLD_SECS])”。同时说明，为魔法数字补充单位换算（如 1048576 // 1MB）是可以的，因为它增加了清晰度而非重复。
文档层级
文件头注释
每个文件都应以简短说明开头，交代其用途以及它在更大系统中如何定位。应包含：该文件/模块负责什么；它为何存在（如果从名称看不出来）；与代码库其他部分的关键关系；任何非显而易见的设计决策。
资料示例（TypeScript）说明某上下文模块管理全应用认证状态、包裹根组件，并解释了为何用 context 而非 Redux：认证状态是读多写少、会话中途很少变化，context 避免了为如此简单的需求引入 actions/reducers 的开销。另一个示例（Swift）说明某重试策略处理失败网络请求的自动重试，使用带抖动的指数退避，以避免服务器恢复后出现惊群，并标注了调用方（Used by）和相关文件（See also）。
函数与方法文档
记录契约，而非实现。应包含：函数完成什么（不是如何完成）；非显而易见的参数约束或边界情况；返回值的含义，尤其是含糊的情况；副作用（网络调用、文件写入、状态变更）。对于简单的 getter、显而易见的一行代码、名称已足够说明问题的私有辅助函数，可以跳过文档。
资料示例中提到：某运费计算函数使用分层定价（1 磅以下统一费率、1-5 磅区域费率、5 磅以上触发货运计算），并对不支持配送的目的地返回 $0 而非抛出异常，调用方如需区分“免运费”与“无法配送”应先检查 canShipTo()。另一个同步函数的示例说明了冲突解决规则（安全设置以服务器为准、UI 偏好以本地为准），以及它在应用进入前台时自动调用，也可从 Settings > Sync Now 手动触发。
内联注释
应节省使用；需要时用于解释推理。资料示例包括：将搜索防抖 300ms 以避免每次按键都请求 API，并说明 300ms 在用户测试中既显得响应及时又将 API 调用减少了约 80%；强制解包在此处安全的原因（viewDidLoad 保证 storyboard 已连接该 outlet，若为 nil 希望立即崩溃而非稍后静默失败）；以及按最早项优先处理的排序，因为较新的项更可能再次被修改，放到最后处理可减少浪费。
架构注释
对于体现重要设计决策的代码，应解释权衡。资料示例包括：购物车采用事件溯源（从事件重建状态，而非直接存储），带来可展示完整购物车历史、可重放事件用于调试、可对过去操作追溯性应用促销等好处，代价是读取当前状态需要重放所有事件，因此将计算结果缓存到 Redis 并设置 5 分钟 TTL；以及为何使用协调者模式组织导航逻辑（各视图控制器互不知晓、深链接变得简单、导航无需实例化 UI 即可测试），代价是更多文件和间接层，对 10 个以上屏幕的应用值得，对简单应用则过度。
TODO 注释
要求可操作、可追溯。资料示例包括：标注 TODO 的负责人、提取到共享工具的前置条件与阻塞来源；标注 HACK 是针对 Safari flexbox bug 的临时方案，并给出在放弃 Safari 14 后移除的说明及缺陷报告链接；标注 FIXME 指出快速切换时的竞态条件，需要取消进行中的请求，并注明复现的 issue 编号。
语言特定模式
资料指出可在 references/language-examples.md 中查看以下语言的详细示例：TypeScript/JavaScript（JSDoc、TSDoc 模式）、Swift（文档注释、MARK pragma）、Python（docstring、类型提示文档）、React/Next.js（组件文档模式）。
限制与缺失信息
资料未提供该技能的安装方式、使用命令、支持的平台或环境要求、收费与价格信息，也未提供具体的使用步骤或效果数据。上述内容暂未提供。