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

itomcoil 2025-06-28 14:29 2 浏览

注释是代码中不可或缺的部分，它能提高代码的可读性和可维护性。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: 此处假设输入已清洗

四、注释的最佳实践

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

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

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

避免过度注释

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

及时更新注释

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

项目统一风格

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

五、注释的常见误用

用注释"注释掉"代码

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

无意义的注释

# 设置x为5
x = 5

过时的注释

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

六、注释工具推荐

文档生成工具

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

代码检查工具

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

IDE支持

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

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

python 函数注释

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

一、单行注释

1. 基本单行注释

2. 单行注释的最佳实践

二、多行注释

1. 使用多个单行注释

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

三、特殊注释

1. 文档字符串（Docstring）

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

3. 调试注释

四、注释的最佳实践

五、注释的常见误用

六、注释工具推荐

相关推荐

我用 1 个 2 手计算器换了 3 台 MacBook(上)

零基础也能搞定!DeepSeek大模型本地安装全攻略

Win7中同时安装python2和python3的方法

Python三目运算符(三元运算符)用法详解

PS零基础入门教程:Photoshop 2024工具详解—标尺工具

按颜色计数、求和、算平均值或最大值?学这个函数就够啦!

SpringBoot中使用LocalDateTime踩坑记录

中药古今研究:人参

「mysql第二次安装不了」mysql安装失败怎么清理干净?

最全的linux安装软件方法 linux安装软件流程