Python函数文档注释怎么写？Google风格Docstring编写指南
为Python函数编写文档注释（Docstring），核心是在函数定义下方使用三引号"""包裹一段说明文字。Google风格并非Python语法强制要求，而是一套被广泛采纳的格式规范。其核心优势在于显著提升代码可读性——遵循该格式编写的文档，无论是通过内置help()函数查看，还是在现代IDE（如PyCharm、VS Code）中获取悬停提示，都能呈现结构清晰、易于理解的说明。
Google风格Docstring的基本格式与结构
Google风格Docstring遵循一个清晰的逻辑结构：首先用一句话概括函数功能，接着空一行，然后详细说明参数、返回值等具体信息。编写时必须严格遵守以下格式规范：所有字段标题（如Args:、Returns:）需顶格书写并以冒号结尾，冒号后需保留一个空格。参数名称必须与函数签名中的变量名完全一致。
初学者常见的错误包括：对Args:进行缩进、参数名拼写不一致、遗漏冒号或空格。这些细节问题可能导致pydoc、Sphinx等文档生成工具无法准确识别和解析参数信息。
Args:每个参数单独成行，格式为参数名 (类型): 描述。类型应使用具体的类型名称，例如str、int、Optional[List[str]]。Returns:说明返回值的类型及其具体含义，例如bool: 文件存在时返回True，否则返回False。Raises:仅列出函数内部主动抛出的异常（如ValueError）。由Python解释器自动触发的运行时异常（如TypeError）通常无需在此处注明。
结合类型提示（Type Hints）编写Args字段
一个常见疑问是：当函数已使用PEP 484引入的类型提示（例如def func(x: int) -> str:）时，Args:字段中是否还需要重复注明类型？答案是肯定的，两者相辅相成，建议保持类型信息一致。这是因为许多开发工具（如VS Code的智能提示）在展示文档时，会同时参考Docstring中的类型描述和函数签名中的类型注解。
立即学习“Python免费学习笔记（深入）”；
这种做法在特定场景下尤为实用，例如团队协作中部分成员关闭了类型检查，或项目需要向后兼容旧版本的Python运行时。
- 避免使用
x (int, optional): ...这类写法，应采用x (Optional[int]): ...，以与类型提示语法保持一致。 - 若参数存在默认值，可在描述末尾补充说明，例如
timeout (float): 请求超时时间，单位为秒。默认值为30.0。 - 应避免风格混用。例如，在Google风格的
Args:中采用x: int（NumPy风格）是不规范的，Google风格要求使用括号将类型括起来。
如何检查与验证Docstring的正确性
最直接的验证方式是在交互式环境或脚本中调用help(你的函数名)，观察输出是否整洁、各字段是否被正确解析。若需进一步验证，可使用pydoc -w 模块名命令生成HTML格式的文档页面，或将格式检查集成到CI/CD流程中，利用pydocstyle等工具进行自动化校验。
使用检查工具时需注意：pydocstyle默认依据PEP 257标准进行检查，需添加--convention=google参数方可适配Google风格。此外，若某个参数的描述需要多行，续行必须进行缩进对齐（通常为4个空格），否则会被误判为新字段的开始。
- 安装检查工具：
pip install pydocstyle - 执行代码检查：
pydocstyle --convention=google 你的模块.py - 常见错误解析： 若出现
D103 Missing docstring in public function，表示某个公开函数缺少Docstring；而D401 First line should be in imperative mood则提示摘要首句应使用祈使语气（例如“解析配置文件并返回字典”），而非以“This function...”开头。
归根结底，比严格对齐格式更重要的是清晰阐述函数逻辑。真正的难点在于准确描述“参数在何种边界条件下会触发何种行为”——例如：strip_whitespace (bool): 是否去除输入字符串的空白字符。若该参数为True且输入值为None，函数将抛出ValueError异常。 像这样明确前提条件与执行结果，远比单纯追求格式对齐更具实际价值。
