文档字符串

文档字符串（Docstring）是写在模块、函数、类定义开头的字符串字面量，用于描述该对象的作用、参数、返回值等信息。它是 Python 的自文档化机制，可以通过 help() 和 __doc__ 属性在运行时访问。

基本格式

def calculate_average(scores):
    """计算分数列表的平均值。
    
    参数:
        scores: 包含数字的列表。
    
    返回:
        平均值，浮点数。如果列表为空返回 0.0。
    """
    if not scores:
        return 0.0
    return sum(scores) / float(len(scores))

文档字符串用三引号 """ 包裹，放在函数体的第一行。第一行是简要描述（一行以内），空行后可以跟详细说明。

访问文档字符串

# 通过 __doc__ 属性
print calculate_average.__doc__

# 通过 help() 函数
help(calculate_average)

help() 会格式化显示文档字符串，包括函数签名和文档内容。

模块级文档字符串

模块文件开头也可以写文档字符串：

"""数学工具模块。

提供常用的数学计算函数，包括平均值、中位数、标准差等。
"""

import math

def calculate_average(scores):
    """计算平均值。"""
    pass

def calculate_median(scores):
    """计算中位数。"""
    pass

模块的 __doc__ 属性就是这个字符串：

import mymath
print mymath.__doc__

类文档字符串

class BankAccount(object):
    """银行账户类。
    
    支持存款、取款、查询余额操作。
    
    属性:
        balance: 当前余额。
    """
    
    def __init__(self, initial_balance=0):
        """初始化账户。
        
        参数:
            initial_balance: 初始余额，默认为 0。
        """
        self.balance = initial_balance
    
    def deposit(self, amount):
        """存款。
        
        参数:
            amount: 存款金额，必须为正数。
        
        返回:
            存款后的余额。
        """
        self.balance += amount
        return self.balance

文档字符串规范

PEP 257 是文档字符串的风格指南，主要建议：

  1. 第一行是简要描述，以句号结尾，不超过一行
  2. 第二行空行
  3. 后续行详细说明参数、返回值、异常等
  4. 描述用命令式语气："计算平均值"而非"计算平均值的函数"
def connect(host, port=80, timeout=30):
    """建立到指定主机的连接。
    
    参数:
        host: 目标主机名或 IP 地址。
        port: 端口号，默认为 80。
        timeout: 超时时间（秒），默认为 30。
    
    返回:
        连接对象。
    
    异常:
        ConnectionError: 连接失败时抛出。
    """
    pass

文档字符串 vs 注释

特性文档字符串注释
位置模块/函数/类开头任意行
语法"""..."""# ...
运行时访问可以（__doc__）不可以
用途描述接口解释实现细节
# 这是注释：解释为什么用 0.0 而不是 0
def calculate_average(scores):
    """计算平均值（文档字符串：描述接口）。"""
    if not scores:
        return 0.0    # 返回 float 保持类型一致（注释：解释实现）
    return sum(scores) / float(len(scores))

自动生成文档

工具可以从文档字符串生成 HTML/PDF 文档：

  • Sphinx：Python 官方文档工具，支持 reStructuredText 格式
  • Epydoc：从 docstring 生成 API 文档
  • pydoc：Python 内置，命令行查看文档
$ pydoc mymodule        # 查看模块文档
$ pydoc -p 8080         # 启动本地文档服务器

单引号 vs 双引号

文档字符串通常用双引号 """，但单引号 ''' 也可以。选择取决于内容：如果文档中包含双引号，用单引号包裹更方便：

def example():
    '''这是一个 "示例" 函数。'''
    pass