Python 文档编写与注释规范

# 注释（Comment）：解释代码"怎么做"
# 使用 # 号，面向开发者
total = sum(items)  # 计算总价

# 文档字符串（Docstring）：解释"是什么"和"怎么用"
# 使用三引号，面向使用者
def calculate_total(items):
    """计算商品列表的总价。
    
    Args:
        items: 商品列表，每个商品包含 price 字段
    
    Returns:
        所有商品价格之和
    """
    return sum(item['price'] for item in items)

def fetch_user(user_id: int, include_profile: bool = False) -> dict:
    """获取用户信息。
    
    根据用户 ID 从数据库获取用户信息，可选择是否包含用户档案。
    
    Args:
        user_id: 用户唯一标识符，必须为正整数。
        include_profile: 是否包含用户档案信息，默认为 False。
    
    Returns:
        包含用户信息的字典，格式如下：
        {
            "id": int,
            "name": str,
            "email": str,
            "profile": dict  # 仅当 include_profile=True
        }
    
    Raises:
        ValueError: 当 user_id 不为正整数时。
        UserNotFoundError: 当用户不存在时。
    
    Examples:
        >>> fetch_user(1)
        {"id": 1, "name": "张三", "email": "zhangsan@example.com"}
        
        >>> fetch_user(1, include_profile=True)
        {"id": 1, "name": "张三", "profile": {"age": 25, "city": "北京"}}
    """
    if user_id <= 0:
        raise ValueError("user_id 必须为正整数")
    
    user = db.get_user(user_id)
    if user is None:
        raise UserNotFoundError(f"用户 {user_id} 不存在")
    
    if include_profile:
        user['profile'] = db.get_profile(user_id)
    
    return user

def linear_regression(X, y, alpha=0.01, iterations=1000):
    """线性回归梯度下降。
    
    使用梯度下降算法拟合线性回归模型。
    
    Parameters
    ----------
    X : array_like
        特征矩阵，形状为 (n_samples, n_features)。
    y : array_like
        目标值，形状为 (n_samples,)。
    alpha : float, optional
        学习率，默认为 0.01。
    iterations : int, optional
        迭代次数，默认为 1000。
    
    Returns
    -------
    theta : ndarray
        拟合后的参数向量，形状为 (n_features,)。
    cost_history : list
        每次迭代的损失值。
    
    Notes
    -----
    学习率过大可能导致不收敛，建议从 0.001 开始调试。
    
    Examples
    --------
    >>> import numpy as np
    >>> X = np.array([[1, 1], [1, 2], [1, 3]])
    >>> y = np.array([2, 4, 6])
    >>> theta, _ = linear_regression(X, y, alpha=0.1)
    """
    pass

# 解释"为什么"而不是"做什么"
# 使用二分查找因为数据已排序，O(log n) 比 O(n) 快
def find_item(sorted_list, target):
    left, right = 0, len(sorted_list) - 1
    while left <= right:
        mid = (left + right) // 2
        if sorted_list[mid] == target:
            return mid
        elif sorted_list[mid] < target:
            left = mid + 1
        else:
            right = mid - 1
    return -1

# 标注 workaround 和 TODO
def get_user_data(user_id):
    # TODO: 迁移到新的用户服务 API（预计 v2.0）
    # FIXME: 临时方案，需要处理超时情况
    response = requests.get(f"{OLD_API_URL}/users/{user_id}")
    return response.json()

# 解释复杂的正则表达式
pattern = r'^(\d{4})-(\d{2})-(\d{2})$'  # YYYY-MM-DD 格式日期

# 标注魔法数字的来源
RETRY_INTERVAL = 5  # 根据运维建议，5 秒重试间隔
MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB，上传限制

# ✗ 注释只是在重复代码
i += 1  # i 加 1

# ✗ 过时的注释（代码已改但注释没更新）
# 返回用户列表
def get_user_count():  # 实际返回的是数量
    return len(users)

# ✗ 用注释代替函数名
def do_stuff(x, y):
    # 这个函数计算两个数的平均值然后乘以 100
    return (x + y) / 2 * 100

# ✓ 应该改为
def calculate_percentage_average(x, y):
    return (x + y) / 2 * 100

# ✗ 注释掉的代码（用 Git 管理历史）
# old_result = process_old_way(data)
# if old_result > threshold:
#     return old_result
result = process_new_way(data)

# 类型提示本身就是最好的文档
# 无需额外注释说明参数类型

def process_order(
    order_id: int,
    items: list[dict[str, int | str]],
    discount: float = 0.0,
    callback: Callable[[int], None] | None = None
) -> dict[str, int | str]:
    """处理订单。
    
    Args:
        order_id: 订单 ID。
        items: 商品列表，每项包含 name(str) 和 quantity(int)。
        discount: 折扣率，0.0-1.0 之间。
        callback: 处理完成后的回调函数。
    
    Returns:
        处理结果，包含 total 和 status。
    """
    pass

# 项目名称

一句话描述项目。

## 功能特性

- 特性 1
- 特性 2
- 特性 3

## 安装

pip install package-name

## 快速开始

```python
from package import Module

m = Module()
result = m.run()

# 安装
pip install pdoc

# 生成 HTML 文档
pdoc ./src/mypackage

# 指定输出目录
pdoc ./src/mypackage -o ./docs

# 启动本地服务器预览
pdoc ./src/mypackage --http localhost:8080

# 安装
pip install sphinx sphinx-autodoc-typehints

# 初始化文档
sphinx-quickstart docs

# 生成 API 文档
sphinx-apidoc -o docs/source ./src/mypackage

# 构建 HTML
cd docs
make html

# docs/source/conf.py
import os
import sys

sys.path.insert(0, os.path.abspath('../../src'))

project = 'My Package'
author = 'Your Name'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',  # 支持 Google/NumPy 风格
    'sphinx_autodoc_typehints',
]

# 使用 Google 风格
napoleon_google_docstring = True
napoleon_numpy_docstring = False

# docs/source/index.rst
.. My Package documentation

Welcome to My Package's documentation!
======================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   installation
   quickstart
   api

API Reference
=============

.. automodule:: mypackage
   :members:
   :undoc-members:
   :show-inheritance:

# 安装
pip install mkdocs mkdocs-material mkdocstrings[python]

# 初始化
mkdocs new docs

# mkdocs.yml
site_name: My Package
theme:
  name: material
  language: zh
  features:
    - navigation.tabs
    - search.suggest

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google

nav:
  - 首页: index.md
  - 安装: installation.md
  - 快速开始: quickstart.md
  - API:
    - 核心模块: api/core.md
    - 工具模块: api/utils.md

# 本地预览
mkdocs serve

# 构建静态站点
mkdocs build

# 部署到 GitHub Pages
mkdocs gh-deploy

def factorial(n: int) -> int:
    """计算阶乘。
    
    >>> factorial(0)
    1
    >>> factorial(1)
    1
    >>> factorial(5)
    120
    >>> factorial(-1)
    Traceback (most recent call last):
        ...
    ValueError: n 必须为非负整数
    """
    if n < 0:
        raise ValueError("n 必须为非负整数")
    if n <= 1:
        return 1
    return n * factorial(n - 1)

# 运行 doctest
# python -m doctest -v script.py
# 或在 pytest 中
# pytest --doctest-modules

"""My Package.

一个简洁的 Python 工具包，提供 XXX 功能。

基本用法:
    >>> from mypackage import Tool
    >>> tool = Tool()
    >>> tool.run()

主要组件:
    - Tool: 主工具类
    - Config: 配置管理
    - helpers: 辅助函数
"""

from .tool import Tool
from .config import Config

__version__ = "1.0.0"
__author__ = "Your Name"
__all__ = ["Tool", "Config"]

# pydocstyle: 检查文档字符串规范
pip install pydocstyle
pydocstyle src/

# Ruff 也能检查文档
ruff check --select D src/

# 配置（pyproject.toml）

[tool.ruff.lint.pydocstyle]
convention = "google"  # 或 "numpy"