注释是代码中不可或缺的部分，它能提高代码的可读性和可维护性。Python支持多种注释方式，各有其适用场景。

一、单行注释

1. 基本单行注释

使用 # 符号，从 # 开始到行尾的内容都会被解释器忽略

# 这是一个单行注释
x = 5  # 这里也可以添加注释

2. 单行注释的最佳实践

• 注释与代码间保留至少2个空格
• 注释内容首字母大写，句尾加句号（英文注释）
• 避免无意义的注释

# 正确的注释示范
radius = 5  # 设置圆的半径为5个单位

# 不好的注释示范
r=5 #半径

二、多行注释

1. 使用多个单行注释

# 这是一个多行注释的示例
# 每行都需要使用#开头
# 适用于简短的多行说明

2. 使用三引号字符串（非正式多行注释）

虽然Python没有真正的多行注释语法，但可以用未赋值的字符串实现

"""
这是一个多行"注释"
通常用于模块/类/函数的文档字符串(docstring)
但也可以作为多行注释使用
"""

三、特殊注释

1. 文档字符串（Docstring）

使用三引号包裹，用于模块、类、函数的说明

def calculate_area(radius):
    """
    计算圆的面积
    
    参数:
        radius (float): 圆的半径
        
    返回:
        float: 圆的面积
    """
    return 3.14 * radius ** 2

2. 类型注解注释（Type Hint）

Python 3.5+ 支持类型注解，可作为特殊注释

def greet(name: str) -> str:
    """
    返回问候语
    
    Args:
        name: 人名
        
    Returns:
        问候字符串
    """
    return f"Hello, {name}"

3. 调试注释

# TODO: 需要添加异常处理
# FIXME: 这里的算法需要优化
# NOTE: 此处假设输入已清洗

四、注释的最佳实践

1. 解释为什么（Why），而不是是什么（What）

# 不好: 将x加1
x += 1

# 好: 补偿数组的0-based索引
x += 1

2. 避免过度注释

• 好的代码应该自解释
• 只注释复杂的业务逻辑或算法

3. 及时更新注释

• 修改代码时同步更新相关注释
• 删除不再适用的注释

4. 项目统一风格

• 团队约定一致的注释格式
• 文档字符串遵循PEP 257规范

五、注释的常见误用

1. 用注释"注释掉"代码

• 临时调试可以，但提交代码前应该删除
• 版本控制工具更适合记录代码变更

2. 无意义的注释

# 设置x为5
x = 5

过时的注释

# 这里需要优化（写于2020年）
# 但代码后来已经被重写过

六、注释工具推荐

文档生成工具

• Sphinx：生成HTML文档
• pdoc：自动生成API文档

代码检查工具

• flake8：检查注释规范
• pylint：评估注释质量

IDE支持

• VS Code：自动生成docstring
• PyCharm：智能注释提示

记住：好的注释应该像好的代码一样精心编写和维护！