Python注释的3种写法**

Python如何注释：详解单行、多行与文档字符串

在Python编程中,注释是代码中不可或缺的一部分，它不仅能帮助开发者记录代码逻辑，还能提高代码的可读性和可维护性，Python提供了多种注释方式，包括单行注释、多行注释和文档字符串（Docstring），本文将详细介绍这些注释的用法、适用场景及最佳实践。

单行注释

单行注释以井号（）开头，适用于简短说明或临时禁用代码。

area = 3.14 * radius ** 2  # 公式：πr²

注意：

• 注释应写在代码上方或行尾,但避免过度堆积行尾注释。
• PEP 8规范建议在后加一个空格，以提高可读性。

多行注释

Python没有专门的多行注释语法,但可通过以下两种方式实现：
方式一：每行以开头

# 这是一个多行注释的示例，
# 通常用于解释复杂逻辑或
# 临时屏蔽大段代码。

方式二：用三引号（或）包裹
虽然三引号实际是字符串，但未被赋值的字符串会被解释器忽略，因此可作为注释使用：

'''
这段代码用于处理用户输入：
1. 验证格式
2. 过滤敏感词
3. 存入数据库
'''

区别：三引号更适合需要保留格式的长文本（如函数说明），而更适合临时注释。

文档字符串（Docstring）

文档字符串是Python特有的功能,用于模块、函数、类或方法的说明，它用三引号定义，可通过__doc__属性访问：

def calculate_area(radius):
    """
    计算圆的面积
    参数:
        radius (float): 圆的半径
    返回:
        float: 面积值
    """
    return 3.14 * radius ** 2
print(calculate_area.__doc__)  # 输出文档字符串

规范建议：

• 遵循PEP 257规范，首行简短总结，空一行后写详细描述。
• 常用工具（如Sphinx）会解析Docstring生成文档。

注释的最佳实践

1. 解释“为什么”而非“做什么”：好的注释应说明代码的意图，而非重复代码行为。

   # 错误示例（冗余）：
   x = x + 1  # 给x加1
   # 正确示例：
   x = x + 1  # 补偿数组索引偏移

2. 避免过度注释：清晰的代码本身即文档，仅注释复杂逻辑或特殊处理。

3. 及时更新注释：修改代码时同步更新注释，避免误导。

4. 使用类型注解补充说明（Python 3.5+）：

   def greet(name: str) -> str:
       """返回欢迎消息"""
       return f"Hello, {name}!"

注释的常见误区

• 用注释屏蔽代码：调试时建议用版本控制（如Git）而非注释代码块。
• 含糊的注释：如# 修复bug应改为# 修复用户未登录时权限校验失败的问题。

Python的注释工具简单但强大,合理使用能显著提升团队协作效率，单行注释适合简短说明，多行注释用于复杂逻辑，而文档字符串则是API设计的核心。优秀的代码是写给人看的，只是恰好能被机器执行。

（全文约680字）