Google Docstring采用三段式结构：简短摘要、空行、详细说明；Args:等字段顶格冒号结尾，参数名与函数签名一致，类型用str等实际名称，Returns:和Raises:需准确描述，类型提示与Docstring类型应保持一致。
Python函数的文档注释（Docstring）用"""包裹，放在函数定义下方第一行；Google风格不是语法强制要求，而是靠格式约定提升可读性——只要结构清晰、字段对齐，help()和IDE就能正确解析。
Google Docstring的基本结构怎么写
核心是三段式：简短摘要 + 空行 + 详细说明（含参数、返回值、异常等）。所有字段名（如Args:、Returns:）必须顶格、冒号结尾、后跟一个空格；参数名需与函数签名完全一致（包括类型提示中的变量名）。
常见错误现象：Args:缩进、参数名拼错、漏掉冒号或空格，会导致pydoc或Sphinx无法提取参数说明。
-
Args:每行一个参数，格式为param_name (type): description，类型用str、int、Optional[List[str]]等实际类型名 -
Returns:写明返回类型和含义，如bool: True if file exists, False otherwise -
Raises:只列明函数主动抛出的异常（如ValueError），不写TypeError这类运行时自动抛出的
带类型提示的函数怎么写Args字段
类型提示（PEP 484）和Docstring的Args:不冲突，但建议保持一致。如果已用def func(x: int) -> str:声明了类型，Args:里仍要写x (int): ...——因为很多工具（如VS Code悬停提示）依赖Docstring里的类型描述，而非仅靠类型提示。
立即学习“Python免费学习笔记（深入）”；
使用场景：团队协作中有人关掉了类型检查，或用的是旧版Python（
- 不要写
x (int, optional): ...，而应写x (Optional[int]): ...，与类型提示语法对齐 - 如果参数有默认值，在描述末尾加
Default is None.或具体值，例如timeout (float): Request timeout in seconds. Default is 30.0. - 避免混用风格，比如在
Args:里写x: int（这是NumPy风格），Google风格强制要求括号包裹类型
怎么验证Docstring是否写对了
最直接的方法是调用help(func)看输出是否整齐、字段是否被识别；更进一步可用pydoc -w module_name生成HTML文档，或集成到CI中用pydocstyle检查格式合规性。
容易踩的坑：pydocstyle默认检查PEP 257，需加--convention=google才按Google风格校验；另外，多行参数描述必须缩进对齐（通常4个空格），否则会被当成新字段。
- 安装检查工具：
pip install pydocstyle - 运行检查：
pydocstyle --convention=google my_module.py - 常见报错
D103 Missing docstring in public function说明函数没写Docstring；D401 First line should be in imperative mood指摘要句不能用This function...开头，得写Parse config file and return dict.
真正难的不是格式，是写清楚“这个参数在什么边界条件下会改变行为”——比如strip_whitespace (bool): Whether to strip whitespace. If True and input is None, raises ValueError. 这种细节，比对齐冒号重要得多。
