在 Python 中为类写注释（文档字符串，Docstring）是提升代码可读性的核心方式，主流遵循 PEP 257 规范（Python 官方文档字符串标准），常用格式有 reStructuredText（reST）、Google 风格、NumPy 风格，其中 Google 风格最简洁易读，新手优先掌握。

一、核心原则

• 类注释写在 class 定义行下方，用三引号（""" 或 '''）包裹；
• 第一行简明描述类的核心功能 / 用途，空一行后补充细节（如参数、属性、示例等）；
• 方法注释和类注释风格统一，优先说明「做什么」，再说明「参数 / 返回值 / 异常」。

二、Google 风格类注释（最常用，推荐）

class PotentialWell3D:
    """三维无限深方势阱的量子特性计算类。

    用于计算三维无限深方势阱中粒子的波函数、能级，并提供可视化方法。
    核心公式基于量子力学中自旋-1/2粒子的势阱模型，支持自定义势阱边长、粒子质量等参数。

    Attributes:
        a (float): 势阱边长，单位为米（m），默认值 1.0。
        hbar (float): 约化普朗克常数，单位为 J·s，默认值 1.055e-34。
        m (float): 粒子质量，单位为 kg，默认值 9.109e-34（电子质量）。

    Examples:
        >>> well = PotentialWell3D(a=1.0)
        >>> energy = well.calc_energy(nx=2, ny=2, nz=2)
        >>> print(f"能级：{energy:.3e} J")
        能级：1.234e-30 J
    """

    def __init__(self, a: float = 1.0, hbar: float = 1.055e-34, m: float = 9.109e-31):
        """类的初始化方法。

        Args:
            a (float, optional): 势阱边长，默认 1.0 m。
            hbar (float, optional): 约化普朗克常数，默认 1.055e-34 J·s。
            m (float, optional): 粒子质量，默认电子质量 9.109e-31 kg。

        Raises:
            ValueError: 若势阱边长 a ≤ 0 时抛出异常。
        """
        if a <= 0:
            raise ValueError("势阱边长必须大于0")
        self.a = a
        self.hbar = hbar
        self.m = m

    def calc_energy(self, nx: int, ny: int, nz: int) -> float:
        """计算三维势阱的能级。

        公式：E = (π²ℏ²)/(2ma²) * (nx² + ny² + nz²)

        Args:
            nx (int): x 方向量子数，正整数。
            ny (int): y 方向量子数，正整数。
            nz (int): z 方向量子数，正整数。

        Returns:
            float: 对应量子数的能级，单位 J。

        Examples:
            >>> well = PotentialWell3D()
            >>> well.calc_energy(1, 1, 1)
            5.098e-31
        """
        return (np.pi**2 * self.hbar**2) / (2 * self.m * self.a**2) * (nx**2 + ny**2 + nz**2)

三、reStructuredText 风格（兼容 Sphinx 文档生成）

        适合需要自动生成官方文档的场景（如开源库）：

class PotentialWell3D:
    """
    三维无限深方势阱的量子特性计算类。

    :param a: 势阱边长，单位 m，默认 1.0
    :type a: float
    :param hbar: 约化普朗克常数，单位 J·s，默认 1.055e-34
    :type hbar: float
    :attribute a: 势阱边长
    :type a: float
    :raises ValueError: 当 a ≤ 0 时抛出
    """
    def __init__(self, a: float = 1.0):
        # 逻辑同上
        pass

四、极简风格（小型脚本 / 快速开发）

        仅保留核心说明，适合简单类：

class PotentialWell3D:
    """三维无限深方势阱计算类，计算波函数和能级。
    
    属性：
        a: 势阱边长（m）
        hbar: 约化普朗克常数（J·s）
    """
    def __init__(self, a=1.0):
        self.a = a