google-python-docstrings

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Python Docstrings Writer

Google风格Python文档字符串编写指南

Write concise, practical Python docstrings that follow the Google Python Style Guide.

编写符合《Google Python风格指南》的简洁、实用的Python文档字符串。

Overview

概述

Focus on API usability: describe what callers need to know, not internal implementation details.
Prefer short, structured sections (
```
Args:
```
,
```
Returns:
```
/
```
Yields:
```
,
```
Raises:
```
,
```
Example:
```
).
Include runnable
```
Example:
```
blocks for public APIs so usage is immediately clear.
Keep language concise and consistent; avoid over-engineered or overly verbose docstrings.

This skill is intentionally trigger-friendly: if a request mentions Python docstrings, documentation cleanup, or Google-style sections, use this skill by default.

聚焦API易用性：描述调用者需要了解的内容，而非内部实现细节。
优先使用简短的结构化章节（
```
Args:
```
、
```
Returns:
```
/
```
Yields:
```
、
```
Raises:
```
、
```
Example:
```
）。
为公共API添加可运行的
```
Example:
```
块，让用法一目了然。
语言保持简洁一致；避免过度设计或过于冗长的文档字符串。

本技能触发条件宽松：如果请求提及Python文档字符串、文档清理或Google风格章节，默认使用本技能。

When to Use This Skill

适用场景

Invoke this skill when the user asks to write docstrings in Google docstring style.

Use this skill when you are:

Writing or updating docstrings for Python modules, classes, functions, or methods.
Standardizing mixed docstring styles into Google-style format.

Adding missing

Args:

Returns:

Yields:

Raises:

Attributes:

, or

Example:

sections.

Improving unclear, verbose, or inconsistent API documentation.
Reviewing existing docstrings for compliance and consistency before merging code.

Do not use this skill when you are:

Writing non-Python documentation (README guides, API specs, or design docs).
Changing runtime behavior, business logic, or code structure unrelated to docstrings.
Generating long tutorials better suited for external documentation.

当用户要求以Google文档字符串风格编写文档时，调用本技能。

在以下场景中使用本技能：

为Python模块、类、函数或方法编写或更新文档字符串。
将混合风格的文档字符串标准化为Google格式。

补充缺失的

Args:

、

Returns:

Yields:

、

Raises:

、

Attributes:

或

Example:

章节。

改进模糊、冗长或不一致的API文档。
在代码合并前，检查现有文档字符串是否符合规范且保持一致。

请勿在以下场景中使用本技能：

编写非Python文档（如README指南、API规范或设计文档）。
修改与文档字符串无关的运行时行为、业务逻辑或代码结构。
生成更适合外部文档的长篇教程。

Output Expectations

输出要求

Produce docstrings that are directly usable in source code with minimal cleanup.
Preserve runtime behavior: edit documentation only unless the user explicitly asks for code changes.
Prefer minimal, focused rewrites over full-document rewrites.
If information is missing, write the safest concise docstring that matches visible API behavior.

生成可直接用于源代码的文档字符串，只需极少的清理工作。
保留运行时行为：仅编辑文档，除非用户明确要求修改代码。
优先选择最小化、聚焦的重写，而非全面重写文档。
如果信息缺失，编写符合可见API行为的最安全简洁的文档字符串。

Progressive Disclosure

渐进式参考

Start with this file for workflow and triggering guidance.
Use
```
references/rules.md
```
for detailed format rules, compliant/non-compliant examples, and final validation.
Consult only the relevant rules section for the object type you are documenting (module, function/method, class).

首先参考本文件获取工作流程和触发指导。
如需详细格式规则、合规/不合规示例及最终验证，请查看
```
references/rules.md
```
。
仅查阅与你正在编写文档的对象类型（模块、函数/方法、类）相关的规则章节。

Quick start

快速入门

Format basics: Use triple quotes (
```
"""
```
), start with a one-line summary (≤80 chars), and add a blank line before details in multi-line docstrings.
Section structure: Use unindented section headers ending with
```
:
```
(e.g.,
```
Args:
```
,
```
Returns:
```
,
```
Raises:
```
,
```
Example:
```
), followed by indented (2 or 4 spaces) content.
Field style: In
```
Args:
```
/
```
Returns:
```
/
```
Raises:
```
, use concise
```
name: Description
```
entries.
Always include
Example:
for every public function or method to show practical usage.
Type hints rule: Omit types in docstrings when the signature is already type-annotated; add type detail only when it improves clarity.
Generators: Use
```
Yields:
```
instead of
```
Returns:
```
.
Classes: Document public attributes in an
```
Attributes:
```
section (same formatting as
```
Args:
```
).

格式基础：使用三引号（
```
"""
```
），以一行摘要开头（≤80字符），多行文档字符串中在详细内容前添加空行。
章节结构：使用无缩进的章节标题，以
```
:
```
结尾（如
```
Args:
```
、
```
Returns:
```
、
```
Raises:
```
、
```
Example:
```
），后续内容缩进（2或4个空格）。
字段风格：在
```
Args:
```
/
```
Returns:
```
/
```
Raises:
```
中，使用简洁的
```
名称: 描述
```
条目。
务必包含
Example:
：为每个公共函数或方法添加该部分，展示实际用法。
类型提示规则：当函数签名已包含类型注解时，文档字符串中省略类型信息；仅在能提升清晰度时添加类型细节。
生成器：使用
```
Yields:
```
替代
```
Returns:
```
。
类：在
```
Attributes:
```
章节中记录公共属性（格式与
```
Args:
```
相同）。

Workflow

工作流程

Determine docstring scope
- Functions: Include
```
Args
```
  ,
```
Returns
```
  (or
```
Yields
```
  ),
```
Raises
```
  , and
```
Example:
```
  as needed.
- Classes: Include class docstring,
```
Attributes:
```
  section for public attributes, and
```
Example:
```
  showing instantiation.
- Modules: Start with a summary, usage example in docstring, and typical import/call pattern.
- Methods: Omit if decorated with
```
@override
```
  (unless behavior materially changes). Include
```
Example:
```
  for public methods.
- Public API rule: Treat names without a leading underscore as public. Private helpers (e.g.,
```
_helper
```
  ) do not require
```
Example:
```
  .
Write the summary line
- Descriptive or imperative style (consistent within file).
- For
```
@property
```
  descriptors, use descriptive style:
```
"""The Bigtable path."""
```
  not
```
"""Returns the Bigtable path."""
```
  .
Structure additional sections
- Add blank line after summary if docstring has multiple lines.
- List sections in order:
```
Args:
```
  ,
```
Returns:
```
  (or
```
Yields:
```
  ),
```
Raises:
```
  ,
```
Example:
```
  .
- Each section name ends with
```
:
```
  , followed by indented content.
- Use consistent indentation (2 or 4 spaces per file).
- Include
```
Example:
```
  for every public function/method to show practical, runnable usage.
Validate before finalizing
- Run through the checklist in
```
references/rules.md
```
  .
- Fix inconsistencies in section headers, summary style, and indentation.
- Ensure examples are realistic and not boilerplate-heavy.

确定文档字符串范围
- 函数：根据需要包含
```
Args
```
  、
```
Returns
```
  （或
```
Yields
```
  ）、
```
Raises
```
  和
```
Example:
```
  。
- 类：包含类文档字符串、公共属性的
```
Attributes:
```
  章节，以及展示实例化的
```
Example:
```
  。
- 模块：以摘要开头，文档字符串中包含用法示例，以及典型的导入/调用模式。
- 方法：如果使用
```
@override
```
  装饰器则无需添加（除非行为发生实质性变化）。为公共方法添加
```
Example:
```
  。
- 公共API规则：将无前导下划线的名称视为公共API。私有辅助函数（如
```
_helper
```
  ）无需添加
```
Example:
```
  。
编写摘要行
- 使用描述性或命令式风格（在同一文件内保持一致）。
- 对于
```
@property
```
  描述符，使用描述性风格：
```
"""The Bigtable path."""
```
  而非
```
"""Returns the Bigtable path."""
```
  。
构建附加章节
- 如果文档字符串为多行，在摘要后添加空行。
- 按以下顺序列出章节：
```
Args:
```
  、
```
Returns:
```
  （或
```
Yields:
```
  ）、
```
Raises:
```
  、
```
Example:
```
  。
- 每个章节名称以
```
:
```
  结尾，后续内容缩进。
- 在同一文件内使用一致的缩进（2或4个空格）。
- 为每个公共函数/方法添加
```
Example:
```
  ，展示实际可运行的用法。
最终验证
- 对照
```
references/rules.md
```
  中的检查清单进行检查。
- 修复章节标题、摘要风格和缩进中的不一致问题。
- 确保示例真实可信，而非大量样板代码。

Common mistakes

常见错误

Writing long narrative paragraphs that restate obvious code behavior.
Repeating type information already present in type annotations.
Using vague sections like
```
Raises: Various exceptions may occur.
```
Skipping
```
Example:
```
for public APIs.
Providing huge setup-heavy examples instead of short, focused usage.

编写冗长的叙述段落，重复代码的明显行为。
重复已在类型注解中存在的类型信息。
使用模糊的章节内容，如
```
Raises: Various exceptions may occur.
```
。
公共API遗漏
```
Example:
```
部分。
提供需要大量前置准备的示例，而非简短聚焦的用法展示。

Best practices

最佳实践

Keep each parameter description to one concise sentence.
Make
```
Example:
```
realistic and quick to read (typically 5-10 lines).
Prefer doctest-style examples (
```
>>>
```
) when practical.
Show expected output when it helps clarify behavior.
Keep style consistent within a file (summary tone, indentation, section order).

每个参数描述保持为一句简洁的句子。
让
```
Example:
```
真实且易于快速阅读（通常为5-10行）。
在可行时优先使用doctest风格的示例（
```
>>>
```
）。
当有助于明确行为时，展示预期输出。
在同一文件内保持风格一致（摘要语气、缩进、章节顺序）。

Reference Files

参考文件

Detailed information available in

references/

```
rules.md
```
: full style description and examples.

详细信息可在

references/

目录中获取：

```
rules.md
```
：完整的风格描述及示例。

Additional Resources

额外资源

Google Python Style Guide: https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings

Google Python风格指南：https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings