Python3注释详解 – 编程小白入门

Python3 注释知识点详解

编程小白也能轻松理解的注释指南，让代码更易读、更专业

什么是注释？

注释是写在代码中的说明文字，用于解释代码的功能、目的或实现方式。Python解释器在执行代码时会完全忽略这些注释。

注释的主要作用：

解释复杂代码的逻辑
记录代码的编写目的
暂时禁用部分代码（调试）
提高代码可读性和可维护性
生成文档（特殊注释）

小白提示

写注释就像给朋友讲解你的代码。想象一下，6个月后的自己或者一个完全不懂编程的人是否能看懂你的代码？

单行注释

单行注释以井号(#)开头，只对同一行中#号后面的内容有效。

                    # 这是一个单行注释

                    print(“Hello, World!”)  # 在代码行末的注释

                    # 下面是一个计算圆面积的代码

                    radius = 5  # 圆的半径

                    area = 3.14 * radius ** 2  # 计算面积

注意： 井号(#)后面需要加一个空格再写注释内容，这样更符合编码规范。

多行注释（块注释）

Python没有专门的多行注释语法，但有两种常用方式实现多行注释：

方法1：每行开头加#号

                    # 这是一个多行注释的示例

                    # 你可以使用多个单行注释

                    # 来组成一个多行注释

                    # 用于解释复杂逻辑

                    # 下面代码的功能：

                    # 1. 获取用户输入

                    # 2. 验证输入有效性

                    # 3. 处理输入数据

方法2：使用三引号（字符串注释）

                    ”’

                    这是一个用三引号实现的多行注释

                    虽然技术上这是一个字符串，但如果不被赋值给变量

                    Python会忽略它，所以可以作为注释使用

                    ”’

                    “””

                    这也是一个多行字符串，可以用作注释

                    双引号和三引号都可以使用

                    “””

使用建议

对于临时注释或者代码文档，推荐使用#号。对于函数/类的文档字符串，使用三引号（下一节会详细讲解）。

文档字符串（Docstrings）

文档字符串是Python特有的一种注释形式，用三引号包裹。它们用于模块、函数、类或方法的说明文档。

                    def calculate_area(radius):
                    “””

                    计算圆的面积

                    参数:

                    radius (float): 圆的半径

                    返回:

                    float: 圆的面积

                    “””

                    return 3.14 * radius ** 2

文档字符串的特点：

位于模块、函数或类的开头
可以使用__doc__属性访问
可以被文档生成工具（如Sphinx）自动提取生成文档
遵循特定的格式规范（如Google风格、NumPy风格等）

注意： 文档字符串不是普通注释，而是对象的一部分，在程序运行时可以访问。

注释的实用技巧

1. 调试时暂时禁用代码

                    # print(“这行代码暂时不需要执行”)

                    # 在调试时，可以注释掉部分代码

                    # 而不需要删除它们

2. TODO注释

                    # TODO: 这里需要添加错误处理

                    # TODO: 优化算法以提高性能

                    # FIXME: 这个函数有时会返回错误结果

3. 注释代码段落

                    # ========================

                    # 数据处理部分

                    # ========================

4. 避免过度注释

                    # 不推荐的注释方式（过度注释）：

                    a = 5  # 将5赋值给变量a

                    b = 10 # 将10赋值给变量b

                    c = a + b  # 将a和b相加，结果赋值给c

注释的最佳实践

解释”为什么”而不是”是什么”：代码本身已经说明它在做什么，注释应解释为什么要这样做
保持更新：修改代码后，记得更新相关注释
使用清晰简洁的语言：避免复杂的术语，除非你的读者是专家
避免不必要的注释：好的代码应该尽可能自解释
遵循PEP 8规范：Python官方代码风格指南
注释与代码对齐：使代码整洁易读

                    # 不推荐的注释（解释”是什么”）：

                    x = x + 1  # x加1

                    # 推荐的注释（解释”为什么”）：

                    x = x + 1  # 补偿数组索引偏移

专业建议

优秀的程序员应该像重视代码一样重视注释。注释是代码的”使用说明书”，能大大提高团队协作效率和代码可维护性。

Python注释要点总结

单行注释使用#符号
多行注释可用多个#号或三引号实现
文档字符串使用三引号，用于模块/函数/类的说明
注释应解释”为什么”而非”是什么”
避免过度注释，但必要的解释不可少
调试时可使用注释暂时禁用代码
使用TODO/FIXME标记待办事项
遵循PEP 8代码风格规范