Python 注释全攻略

1. 单行注释

语法

使用 # 符号后接注释内容。例如：

# 示例注释
print("Hello, World!")  # 也可以在一行代码末尾加注释

作用

• • 提高代码可读性，便于日后复查或团队协作。
• • 解释代码逻辑、参数含义或注意事项。
• • 可用于临时屏蔽部分代码进行调试。

使用建议

• • 注释需简明扼要，避免重复代码本意。
• • 在代码结尾处添加注释时，建议在 # 前留两个空格。
• • 不要在代码中过度添加无意义注释，避免“注释污染”。

2. 多行注释

语法

用三个单引号 ''' ... ''' 或三个双引号 """ ... """ 包裹多行文本：

'''
多行注释示例
可编写多行内容
'''
"""
同样是多行注释范例
"""

实际用途

• • Python 并无专门的多行注释语法，以上两种方式本质为字符串（没有赋值时，解释器会忽略），可用作多行注释。
• • 常用于书写函数、类、模块的文档字符串（docstring）：

def add(a, b):
    """
    加法函数
    :param a: 加数1
    :param b: 加数2
    :return: 两数之和
    """
    return a + b

利用 help() 可查看对应帮助信息。

注意

• • 文档字符串需置于定义体第一行，否则无法被自动工具识别、提取。
• • 如需彻底避免字符串对象生成，多行注释建议使用多行 #。

3. 特殊注释

3.1 #!/usr/bin/env python

背景

在 Linux 和 macOS 等类 Unix 系统中，命令行运行脚本时需声明该脚本使用哪种解释器。首行的 “shebang” 用于此目的。

说明

• • #! 为 shebang，后跟解释器路径，一般放在文件首行。
• • /usr/bin/env 用于按当前环境 PATH 查找并调用指定解释器。
• • “python” 告诉系统用 Python 解释此脚本，无需关心具体安装路径。
• • 这种写法适配不同环境、虚拟环境、conda、pyenv 等，增强跨平台兼容性。

示例

#!/usr/bin/env python
print("Hello!")

将脚本赋予可执行权限（chmod +x filename.py）后，即可使用 ./filename.py 直接运行，无需每次输入 python filename.py。

早期做法

• • 早先常用 #!/usr/bin/python，假定解释器在此目录，但不同系统、环境下路径不固定。

推荐写法

• • 建议使用

#!/usr/bin/env python3

明确指定 python3，避免 python2/3 混淆。例如：

#!/usr/bin/env python3

• • 避免硬编码绝对路径，增强脚本适用性。

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

背景

• • Python 2 源码默认采用 ASCII 编码，代码中书写非 ASCII 字符（如中文）会报错。

说明

• • 在文件首部添加编码声明，使 Python 按指定字符集解释源码。
• • 通用写法：

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

• • 可根据实际需要使用如 gbk、latin-1 等其他编码。

Python 3 说明

• • Python 3 默认源码采用 UTF-8 编码，一般无需再声明编码即可正常书写多语言字符。
• • 若需兼容 Python 2 或多系统开发、团队协作，建议继续声明编码，确保稳定性。

推荐写法

• • 在代码文件开头（通常为第一、二行，shebang 最前）写明：

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

• • 对于纯 Python 3 项目声明编码可选，但增加兼容性无坏处，也方便跨平台协作。

总结

这些注释不仅提升代码可读性，还能增强代码的规范性、通用性和可维护性。良好的注释是专业开发不可或缺的技能。