Python3 注释

概念与用途

注释解释代码为何如此设计，解释器会忽略以 # 开始到行末的内容。文档字符串不是普通注释，而是模块、类或函数的运行时 __doc__，可被 help() 和文档工具读取。

核心语法

行内注释应简短；公开 API 可用三引号文档字符串说明目的、参数和异常。类型信息优先使用类型注解，不要维护容易过期的伪类型注释。

def divide(total: float, count: int) -> float:
    """返回平均值；count 必须为正整数。"""
    if count <= 0:
        raise ValueError("count 必须大于 0")
    return total / count

print(divide.__doc__)
print(divide(10, 2))

文档层次

载体	面向对象	内容
行注释	维护者	非显然的原因与约束
docstring	API 使用者	契约、参数、返回和异常
README	项目使用者	安装、运行和架构入口
ADR	团队	重要设计决策及取舍

示例：模块文档字符串

"""温度转换工具。

所有公开函数接收摄氏度，返回浮点结果。
"""

def to_fahrenheit(celsius: float) -> float:
    """把摄氏度转换为华氏度。"""
    return celsius * 9 / 5 + 32

print(help(to_fahrenheit))

文档应与代码一同评审和测试。示例若可执行，可放入 doctest 或文档测试，减少接口改变后说明失真的风险。

常见错误与工程注意

• 三引号字符串只有处在规定位置才是文档字符串，不能用它随意注释代码块。
• 注释应解释约束和动机，不要重复显而易见的赋值动作。
• TODO 应包含问题链接或退出条件，避免永久遗留模糊标记。