Python 社区有多个流行的文档注释风格，包括 reStructuredText（Sphinx 默认）、NumPy 风格和 Google 风格。相比前两种，Google 风格的可读性最高，结构清晰，被越来越多的开源项目采用。然而手写 Google 风格 docstring 容易忽略缩进、空行和类型描述等细节，CodeGeex 这类代码大模型恰好可以补足这一短板。下面先介绍 Google 风格的核心语法，再演示如何用 CodeGeex 批量生成规范注释。
Google 风格 docstring 的核心语法
Google 风格 docstring 由几个固定区块组成：函数描述、Args、Returns、Raises，有时还有 Yields 和 Examples。每个区块使用“键:”加缩进列表的方式组织。描述部分直接写在三引号之后，不需要加空行；Args 和 Returns 区块前必须空一行，区块内部每个参数占一行，参数名和类型之间用冒号分隔，描述与类型之间用两个空格或四个空格缩进。下面是一个正确的示例：
def fetch_user(user_id: int, include_profile: bool = False) -> dict:
"""根据用户 ID 获取用户信息。
从缓存或数据库中读取用户数据，可选择是否附带详细资料。
Args:
user_id: 用户的唯一标识符。
include_profile: 是否包含用户的扩展资料，默认仅返回基础信息。
Returns:
dict: 包含用户信息的字典，至少包括 id、name 和 email 三个键。
Raises:
ValueError: 当 user_id 小于等于 0 时抛出。
KeyError: 当用户不存在时抛出。
"""
if user_id <= 0:
raise ValueError("user_id must be positive")
# 省略实际查询逻辑
return {"id": user_id, "name": "Alice", "email": "alice@ippipp.com"}
注意上面代码中 -> 表示函数返回类型注解，而 docstring 的 Returns 区块单独描述返回值；两者并不冲突。Google 风格要求 Args 区块里的参数顺序与函数签名一致，且不建议写“self”参数，因为类方法中的 self 属于调用约定而非业务参数。另外，如果某个参数是关键字专用参数，可在参数名后加括号注明，例如 timeout (int, optional)。
很多新手容易在区块之间漏掉空行，或者在参数描述前面使用了不统一的缩进。CodeGeex 生成的注释默认遵循 PEP 8 与 Google 风格指南，但前提是提示词中明确声明“Google style docstring”并给出函数上下文。若直接让模型“写注释”，它可能生成 NumPy 风格或混合风格。
CodeGeex 生成文档注释的工作流程
CodeGeex 支持通过注释或自然语言触发代码补全。要生成 Google 风格 docstring，最有效的方式是在函数定义下方输入三个双引号后暂停，让模型接着补全剩余部分。如果希望更可控，可以在函数上方用注释说明要求。例如：
# 为下面的函数生成 Google 风格 docstring，包含 Args、Returns、Raises
def calculate_discount(price: float, member_level: str) -> float:
"""计算折扣后的价格。
Args:
price: 商品原价，必须大于0。
member_level: 会员等级，可选值为 'normal'、'silver'、'gold'。
Returns:
float: 折扣后的实际支付金额，四舍五入到两位小数。
Raises:
ValueError: 当 price 小于等于0或 member_level 不合法时抛出。
"""
# 假设有折扣逻辑
pass
上面的示例展示了 CodeGeex 在函数体尚未编写时补全 docstring 的能力。实际使用中，可以先写函数签名和主要业务逻辑，再回头让模型生成 docstring。此时在函数定义第一行末尾输入冒号并换行，然后输入三个双引号，CodeGeex 会结合函数体内的变量名和返回值智能推断参数含义。例如函数体内出现了 tax_rate = 0.06，模型可能会把参数 tax_rate 描述为“税率，默认值为 0.06”，这种推断能力比单纯的模板填充更准确。
另一个重要技巧是调整 CodeGeex 的生成长度和多样性参数。文档注释偏长且需要完整结构时，可以将模型的输出 token 上限调高，或使用“// generate a complete Google-style docstring with examples”这类前缀触发完整输出。如果模型只生成了 Args 而遗漏了 Returns，可以手动补充“Returns:”后让模型继续，CodeGeex 支持这种交互式续写。
用 CodeGeex 批量处理旧代码库的注释补全
对于体量较大的遗留项目，逐一让模型生成 docstring 效率依然不高。更推荐的做法是编写一个脚本，利用 CodeGeex 的 API 接口批量请求。下面是一个简化的调用示例，演示如何通过 HTTP 请求提交函数源码并获取带 docstring 的新代码：
import requests
API_URL = "https://api.codegeex.cn/v1/completions"
API_KEY = "your_api_key_here"
def add_google_docstring(func_source: str) -> str:
prompt = f"请为以下 Python 函数添加 Google 风格 docstring，包含 Args、Returns、Raises，只输出完整函数代码：\n\n{func_source}"
payload = {
"model": "codegeex-4",
"prompt": prompt,
"max_tokens": 512,
"temperature": 0.2,
}
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.post(API_URL, json=payload, headers=headers)
resp.raise_for_status()
return resp.json()["choices"][0]["text"]
上述脚本中 temperature=0.2 是为了让输出更稳定，避免生成过程加入过多创造性描述。批量处理时需要对每个函数的返回结果做语法校验，防止模型偶尔插入中文标点或错误的缩进。可以使用 Python 的 ast 模块解析函数源码，若解析失败则回退到原始代码并记录日志。
此外，CodeGeex 提供了 IDE 插件，在 PyCharm 和 VS Code 中可以直接选中函数名，使用右键菜单里的“Generate Docstring”功能。该功能内部已集成了 Google 风格模板，生成后自动替换原有注释。对于已有旧式注释的函数，插件会尝试合并信息，避免丢失原作者留下的重要备注。这种方式特别适合团队中不熟悉 Google 风格的成员，能够逐步统一代码库的注释规范。
需要提醒的是，CodeGeex 生成的 docstring 只是候选内容，开发者必须核对参数描述是否与实际业务一致。比如函数参数名为 data，模型可能根据常见用法描述为“JSON 字符串”，但实际传入的是字典对象。因此批量生成后应结合类型注解或单元测试进行校正。
整个流程可以总结为：先定义清晰的 Google 风格模板，再借助 CodeGeex 的补全能力填充具体内容，最后通过代码审查和工具检查保证质量。这三步配合起来，能够在不牺牲可读性的前提下，大幅降低文档注释的维护成本。
CodeGeexPython文档注释Google规范修改时间：2026-08-24 14:59:26