python入门到脱坑—Python注释详解

大家好，欢迎来到IT知识分享网。

注释是代码中不可或缺的部分，它能提高代码的可读性和可维护性。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：智能注释提示

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