编写清晰、规范的注释是专业软件开发的重要一环。在 Python 中，我们不使用 # 作为规范的注释，而是使用文档字符串（Docstrings）。这不仅是为了让人读懂代码，更是为了让工具（如 IDE、文档生成器）能够理解和利用这些信息。
什么是 Docstring？
Docstring 是出现在模块、函数、类或方法定义的第一个语句，用三引号 """ 或 ''' 包围。它会成为该对象的 __doc__ 属性，可以被 help() 函数和各种工具提取。
主流 Docstring 规范
目前最主流的两种 Docstring 规范是 reStructuredText (reST) 和 Google 风格。PyCharm 默认支持并推荐 reST，但可以轻松切换到 Google 风格。
1. reStructuredText (reST) 风格（PyCharm 默认）
reST 是 Python 官方文档和许多大型项目（如 Sphinx）使用的标准格式。
函数/方法注释示例：
def calculate_area(radius: float) -> float:
"""计算圆的面积。
这是一个更详细的描述，说明函数的功能和使用的公式。
:param radius: 圆的半径，必须为正数。
:type radius: float
:return: 计算出的圆的面积。
:rtype: float
:raises ValueError: 如果半径为负数。
"""
if radius < 0:
raise ValueError("半径不能为负数")
return 3.14159 * radius * radius
类注释示例：
class DataProcessor:
"""用于处理和清洗数据的工具类。
该类提供了一系列静态方法，用于执行常见的数据清洗任务。
:ivar batch_size: 处理数据时的批次大小。
:vartype batch_size: int
"""
def __init__(self, batch_size: int = 100):
self.batch_size = batch_size
2. Google 风格
Google 风格因其出色的可读性而广受欢迎，结构更像是带标题的段落。
函数/方法注释示例：
def calculate_area(radius: float) -> float:
"""计算圆的面积。
这是一个更详细的描述，说明函数的功能和使用的公式。
Args:
radius (float): 圆的半径，必须为正数。
Returns:
float: 计算出的圆的面积。
Raises:
ValueError: 如果半径为负数。
"""
if radius < 0:
raise ValueError("半径不能为负数")
return 3.14159 * radius * radius
类注释示例：
class DataProcessor:
"""用于处理和清洗数据的工具类。
该类提供了一系列静态方法，用于执行常见的数据清洗任务。
Attributes:
batch_size (int): 处理数据时的批次大小。
"""
def __init__(self, batch_size: int = 100):
self.batch_size = batch_size
在 PyCharm 中高效实践
PyCharm 提供了强大的功能来简化 Docstring 的编写。
-
自动生成模板
- 在一个函数或类的定义行下方，输入
"""或''' - 按下 Enter (回车) 键
- PyCharm 会立即根据函数的签名（参数、返回值等）自动生成一个 Docstring 骨架，您只需填充描述即可
- 在一个函数或类的定义行下方，输入
-
切换 Docstring 格式
- 打开 Settings/Preferences (macOS: ⌘, | Windows/Linux: Ctrl+Alt+S)
- 导航到 Tools → Python Integrated Tools
- 在 Docstrings 部分，将 Docstring format 从 "reStructuredText" 修改为 "Google" 或其他您喜欢的风格
至此，我们已经将今天讨论的所有核心主题都整理成了文档。希望这些总结对您有所帮助！