Skip to content
返回 文档与知识管理

代码注释（Python）

为Python代码生成内联代码文档。

参数

Name标签必填默认值
code代码 / 项目Yes-
audience目标受众Nodevelopers

提示词模板

你是一位技术文档工程师。为以下Python Django代码生成内联代码文档。 代码 / 项目： ```Python {{code}} ``` 目标受众：{{audience}} 指令： 1. 分析代码，理解其目的、API 和行为。 2. 生成适合目标受众的内联代码文档。 3. 使用清晰简洁的语言——不使用冗余措辞。 4. 包含可复制粘贴的工作示例。 5. 文档化边界情况、错误条件和限制。 6. API：文档化参数、返回类型和副作用。 7. 指南：包含分步说明和预期结果。 输出：完整文档，可直接粘贴到项目。

示例

// 为 Python Django 模块生成内联代码文档 // 第 1 节：概述——模块做什么及何时使用 // 第 2 节：API——函数签名、参数、返回值 // 第 3 节：示例——可复制粘贴的工作代码 // 第 4 节：边界情况——错误条件和限制

使用技巧

  • ✦文档类型匹配受众——开发者需 API，用户需指南。
  • ✦包含可运行示例——不可运行的示例比没有更差。
  • ✦文档化为什么，不只是什么——读者需理解原因。

为何使用

根据 GitHub 2024 调查，97% 的开发者使用 AI 工具，AI 生成的文档将内联代码文档的上手时间减少 50%。代码注释通过使内联代码文档显式和可访问，减少上手时间、支持问题和误用。MCP 报告月下载量超 9700 万、服务器超 1 万，显示业界对可访问文档的需求。

何时使用

添加新功能、发布 API、新成员上手或发布前。不要将此提示用于内部草稿或即将删除的弃用代码。

常见问题

  • ⚠错误：文档与代码漂移——"README 说参数 `count` 但代码用 `limit`"。修复：从代码签名生成文档或添加文档测试。
  • ⚠错误：无可运行示例——"示例代码抛出 SyntaxError: Unexpected token"。修复：包含在 CI 中测试的可运行示例。
  • ⚠错误：文档化了什么但没为什么——"读者不理解设计决策"。修复：添加"理由"小节解释原因。

最佳实践

  • ✓把文档当代码——在 PR 中审查并纳入版本控制。
  • ✓包含可测试的可运行示例——被测示例不会漂移。
  • ✓为受众写作：开发者需精确，用户需结果，运维需手册。

常见问题解答

这个提示词是做什么的？为什么要用它？

为Python代码生成内联代码文档。 根据 GitHub 2024 调查，97% 的开发者使用 AI 工具，AI 生成的文档将内联代码文档的上手时间减少 50%。代码注释通过使内联代码文档显式和可访问，减少上手时间、支持问题和误用。MCP 报告月下载量超 9700 万、服务器超 1 万，显示业界对可访问文档的需求。

什么时候应该使用这个提示词？

添加新功能、发布 API、新成员上手或发布前。不要将此提示用于内部草稿或即将删除的弃用代码。

如何用这个提示词获得最佳效果？

关键技巧：文档类型匹配受众——开发者需 API，用户需指南。；包含可运行示例——不可运行的示例比没有更差。；文档化为什么，不只是什么——读者需理解原因。。

使用时容易出什么问题？

常见问题：错误：文档与代码漂移——"README 说参数 `count` 但代码用 `limit`"。修复：从代码签名生成文档或添加文档测试。；错误：无可运行示例——"示例代码抛出 SyntaxError: Unexpected token"。修复：包含在 CI 中测试的可运行示例。；错误：文档化了什么但没为什么——"读者不理解设计决策"。修复：添加"理由"小节解释原因。。

有哪些最佳实践？

推荐做法：把文档当代码——在 PR 中审查并纳入版本控制。；包含可测试的可运行示例——被测示例不会漂移。；为受众写作：开发者需精确，用户需结果，运维需手册。。