Claude Code文档生成：3个技巧让代码自动写文档

好的，没问题。这篇“AI味儿”确实有点重，结构太工整了。我这就给它注入点“人味儿”，让它更像是一个踩过坑的程序员在跟你唠嗑。

—

后来我花了一整个周末跟它死磕，才发现Claude Code写文档这事，关键真不在于“它能不能写”，而在于“你到底知不知道怎么让它写出点有用的东西来”。

先来看我踩的第一个坑。我当时以为它看了我的代码就什么都懂了，但其实呢，它只看了一小段代码片段。

**开篇配图：一张截图展示Claude Code生成的“废话文档”，比如“这个函数用于处理数据”，旁边标注“这不是你想要的”**

一、别让Claude当“文档打字员”

好多人用Claude生成文档都是这么干的：打开一个文件，选中代码，然后输入“给这个函数写文档”。

结果出来的是啥？

“`python
# 处理数据
def process_data(input_data):
# 对输入数据进行处理
result = input_data * 2
return result
“`

这跟没写有啥区别？ “处理数据”这四个字，我难道不知道吗？问题是你倒是说说它在处理什么数据啊！

我后来发现，Claude之所以写出这种废话，是因为它根本不知道这个函数是干嘛的。它只知道“有个函数叫process_data”，但它不知道这个数据是用户填的表单，还是API返回的响应，更不知道这个“乘以2”是为了算积分还是算折扣。

所以我琢磨出一个办法：**给它喂上下文**。不是让它瞎猜，而是把背景故事告诉它。

“`markdown
# 上下文：这是电商订单处理模块的一部分
# 函数名称：process_data
# 功能描述：根据促销规则计算用户实际支付的积分倍数
# 输入：用户提交的订单数据（包含原始积分、促销活动ID）
# 输出：调整后的积分值
# 注意事项：促销活动ID为0时表示无促销，不进行任何调整

def get_promotion(promotion_id):
# 模拟从数据库获取促销活动信息
promotions = {101: {‘multiplier’: 2}, 102: {‘multiplier’: 3}}
return promotions.get(promotion_id, {‘multiplier’: 1})

def process_data(input_data):
if input_data[‘promotion_id’] == 0:
return input_data[‘original_points’]

# 根据促销活动调整积分
promotion = get_promotion(input_data[‘promotion_id’])
return input_data[‘original_points’] * promotion[‘multiplier’]
“`

这次Claude生成的文档就好多了：

“`python
def process_data(input_data):
“””
根据促销规则计算用户实际支付的积分倍数

Args:
input_data (dict): 用户订单数据，包含:
– original_points (int): 用户原始积分
– promotion_id (int): 促销活动ID，0表示无促销

Returns:
int: 调整后的积分值

Example:
>>> process_data({‘original_points’: 100, ‘promotion_id’: 101})
200 # 假设促销活动101的倍数为2
“””
“`

一开始我也觉得这个设计有点反人类——为什么我得先写一堆东西，再让AI写？但实践证明，这比让它瞎猜强了10倍。我试了几次，感觉加上上下文后，一次过的概率高多了，省了我好多来回改的功夫。

二、用“文档模板”锁定输出格式

另一个踩过的坑是格式。Claude默认生成的文档，有时候是Google风格，有时候又是NumPy风格，有时候干脆自创一种格式，看得我脑壳疼。我们团队有自己的一套规范，要对接文档生成工具，格式不统一后续处理就麻烦大了。

于是我想了个办法：**自己定义文档模板**。给它一个框框，让它照着填。

“`python
# Claude Code文档生成模板（Python版）
DOC_TEMPLATE = “””
{function_name}函数文档模板

函数描述
{一句话说明函数的作用}

参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|——–|——|——|——–|——|
| {param_name} | {param_type} | {required} | {default} | {description} |

返回值
{返回类型}: {返回说明}

异常
{可能抛出的异常和触发条件}

示例
“`python
{使用示例}
“`

性能说明
{时间复杂度、空间复杂度，如果有}
“””
“`

然后我就让Claude严格按照这个模板来填。注意，模板里用的不是真实数据，而是占位符，这样它才知道该往哪里填什么。实际使用时，你可以用Python的`str.format`或f-string把这些占位符替换成真实内容，比如`DOC_TEMPLATE.format(function_name=”calculate_discount”, …)`。

实际用起来是这样的：

“`
请为以下代码生成文档，严格按照此模板格式，不要增加或减少任何字段：

模板：
{function_name}函数文档模板

函数描述
{一句话说明函数的作用}

参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|——–|——|——|——–|——|
| {param_name} | {param_type} | {required} | {default} | {description} |

返回值
{返回类型}: {返回说明}

代码：
def calculate_discount(price, coupon_code=None, user_level=1):
# 计算折扣
if coupon_code is not None and coupon_code != ” and user_level > 0:
return price * 0.9
return price
“`

结果：

“`
calculate_discount函数文档模板

函数描述
根据优惠券和用户等级计算折扣价格

参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|——–|——|——|——–|——|
| price | float | 是 | 无 | 原始商品价格 |
| coupon_code | str | 否 | None | 优惠券编码，无优惠券时传None |
| user_level | int | 否 | 1 | 用户等级，1为普通用户，等级越高折扣越大 |

返回值
float: 折扣后的价格

异常
无显式异常抛出

示例
“`python
calculate_discount(100.0, coupon_code=’VIP2024′, user_level=2)
# 返回 90.0
“`

性能说明
时间复杂度: O(1)，空间复杂度: O(1)
“`

看到没？格式统一了，内容也不废话了。而且这个模板可以直接粘贴到项目的文档生成工具里，省了我好多事儿。

对了，还有个技巧：**在模板末尾加一个“字段完整性检查”**。比如写上“如果某个字段没有对应内容，请填‘N/A’或‘无’，不要留空”。这样能保证输出的文档不会缺胳膊少腿。

**配图：性能说明, 模板里可以加一个“字段完整性检查”**

本文档仅供学习参考，实际使用时请根据项目规范调整。
本文由AI辅助创作，仅供参考。