注释与文档字符串

# 开始单行注释，直到该物理行结束。注释应解释“为什么”，不要重复代码已经表达的“做什么”。

timeout_seconds = 30  # 上游服务的约定超时，不是默认网络超时

三引号创建的是字符串，不是注释。只有模块、类或函数体的第一条语句中的字符串会成为文档字符串（docstring），可被 help() 和 __doc__ 读取：

def normalize_email(value: str) -> str:
    """去除首尾空白并统一为小写。"""
    return value.strip().lower()

不要使用未赋值的三引号字符串模拟块注释；它仍会作为运行时常量出现在代码对象中。临时禁用代码使用版本控制或删除代码，而不是将其注释掉。

参考

• Python 词法分析：注释
• Python 文档字符串约定