Python 注释详解

注释是代码中不可或缺的部分，用于解释代码功能、增加可读性，不会被 Python 解释器执行。合理使用注释能极大提升代码可维护性。

一、注释类型与语法

# 这是单行注释 - 计算折扣价
discount = 0.85  # 默认85折优惠

"""
多行注释示例：
该函数计算商品总价
支持批量计算和折扣应用
"""
def calculate_total(items, discount=1.0):
    ...

二、注释的核心作用

1. 解释代码意图

# 使用二分查找优化搜索效率（O(log n)）
left, right = 0, len(arr)-1

   2.标记待办事项

# TODO: 添加缓存机制提升性能
# FIXME: 边界条件需处理异常

  3.屏蔽调试代码

# print(f"调试值: {result}")  # 临时输出

 4.生成文档（通过文档字符串）

def connect_database(host, port):
    """建立数据库连接
    
    参数:
      host (str): 数据库主机地址
      port (int): 数据库端口号
    
    返回:
      Connection: 数据库连接对象
    """

三、文档字符串（Docstring）规范

位置要求：

• 模块顶部

• 函数/类定义后首行

• 类方法内部

三种主流格式：

1. Google 风格

def add(a, b):
    """计算两数之和
    
    Args:
        a (int): 第一个加数
        b (int): 第二个加数
    
    Returns:
        int: 两数之和
    """
    return a + b

   2.Numpydoc 风格

def split_string(text, sep):
    """分割字符串
    
    参数
    ----------
    text : str
        待分割字符串
    sep : str
        分隔符
    
    返回
    -------
    list
        分割后的子串列表
    """

   3.Epytext 风格

class Circle:
    """圆形类
    
    @ivar radius: 圆半径
    @type radius: float
    """
    def __init__(self, radius):
        self.radius = radius

  查看文档字符串：

print(add.__doc__)  # 输出函数文档
help(add)           # 查看完整帮助

四、注释的最佳实践

✅ 该写的注释

# 解释复杂算法逻辑
# 说明重要设计决策
# 描述接口参数和返回值
# 标记临时解决方案

❌ 不该写的注释

# 变量定义（明显含义无需解释）
count = 0  # ❌ 糟糕示例："设置count为0"

# 直译代码（冗余）
result = a + b  # ❌ 糟糕示例："将a和b相加"

📝 优质注释原则：

1. 简洁清晰：避免冗长描述

2. 同步更新：修改代码时同步更新注释

3. 英文优先：团队协作推荐英文注释

4. 避免废话：注释应提供代码之外的信息

# 好注释：处理闰年特殊情况
if year % 400 == 0 or (year % 4 == 0 and year % 100 != 0):

五、特殊注释技巧

1. 文件编码声明（Python 2 必需）

# -*- coding: utf-8 -*-

   2.解释器路径指定（Unix/Linux）

#!/usr/bin/env python3

  3.类型提示注释（兼容旧版本）

def greet(name: str) -> str:  # Python 3.5+ 原生支持
    # type: (str) -> str     # Python 2.7/3.4 兼容写法
    return "Hello, " + name

 4.条件执行注释

if __debug__:
    print("调试模式")  # -O 选项运行时跳过

六、注释工具链

1. 文档生成：

   • Sphinx：生成HTML/PDF文档

   • pdoc：自动生成API文档

2. 静态检查：

   • flake8：检查注释规范

   • pylint：评估注释覆盖率

3. 文档测试：

def square(n):
    """计算平方
    
    >>> square(4)
    16
    >>> square(-3)
    9
    """
    return n * n

if __name__ == "__main__":
    import doctest
    doctest.testmod()

注释的哲学

"好的代码应当像诗一样自解释，但当诗需要注释时，注释应像诗的注解一样优雅。"
—— 源自《Python之禅》

黄金法则：

• 优先写清晰代码，次之加注释

• 注释解释 为什么，代码展示 怎么做

• 公共API必须包含完整文档字符串