文案写作 通用 中文 English 内联文档 在本仓库中为 [file \/ module \/ function] 添加或改进内联文档(JSDoc、文档字符串、注释)。目标是:… 生成后的提示词 在本仓库中为 `[file \/ module \/ function]` 添加或改进内联文档(JSDoc、文档字符串、注释)。目标是:让未来的开发者理解那些并不显而易见的决策,而不是重复代码已经说明内容的噪音。 ## 步骤 1. **先阅读代码** - 追踪每个函数、类和模块实际做了什么;记录边界情况和不明显的行为。绝不要仅凭签名来写文档。 2. **遵循仓库约定** - 检查现有文档字符串风格:格式(JSDoc、reST、Google、NumPy)、详细程度,以及文档在何处使用或被有意省略。严格匹配。 3. **记录重要内容** - 公共函数和类、非显而易见的参数(有效值、默认行为)、本身不能自解释的返回值、副作用和变更、错误条件及抛出时机,以及代码令人意外处的“为什么”注释。 4. **跳过显而易见的内容** - 不要为简单的 getter 和 setter、单行函数、清晰的私有辅助函数或自明的参数写文档。 5. **保持简洁** - 大多数函数一到三行,复杂类最多一段。每句话都必须补充代码尚未表达的信息。 6. **验证准确性** - 将每条文档对照代码重新阅读,并修正任何描述了实现并不具备的行为的内容。 ## 验证 - [ ] 已匹配仓库现有的文档字符串或 JSDoc 风格,包括其格式。 - [ ] 每条文档注释都已对照代码回读,并且按所写内容准确无误。 - [ ] 没有文档字符串只是复述函数名、参数名或显而易见的内容。 - [ ] 公共 API、非显而易见的逻辑和每种失败模式都已记录;简单的 getter 和 setter 则没有。 - [ ] 注释保持简洁,且没有用 TODO 代替已写好的文档。 ## 规则 - 绝不要编写复述函数名或参数名的文档字符串(“这个函数接收一个名字并返回问候语”)。 - 绝不要仅为达到覆盖率目标而添加文档——质量优先于数量。 - 绝不要在文档中使用 TODO 注释——要么写好文档,要么删除占位符。 - 如果代码复杂到无法简洁地写文档,代码可能需要重构,而不是写更长的文档。 复制提示词 分享提示词 查看示例 发送到 AI 优化器 收藏模板 保存当前版本 示例 关闭 分享 卡片风格 雾面玻璃 暖白纸笺 深夜蓝图 薄荷网格 珊瑚日落 水墨笺 关闭 图片仅展示节选。