跳转至

00 注释的用法

python 注释详解

注释是代码中用于解释或说明的文字，不会被解释器执行。 主要功能包括：

  • 提高代码可读性，便于他人理解代码逻辑。
  • 临时禁用代码（调试时常用）。
  • 记录代码作者、版本或修改信息。

单行注释

以 # 开头，作用于该符号后的整行内容，适用于简短说明或临时注释单行代码。

1
2
3
# 计算圆的面积
radius = 5
area = 3.14 * radius ** 2  # 公式: πr²

多行注释

通过三引号 ''' 或 """ 实现，常见于函数或模块的文档字符串。

1
2
3
4
5
6
7
8
"""
函数: calculate_area  
功能: 根据半径计算圆面积  
参数: radius (float)  
返回: area (float)  
"""
def calculate_area(radius):
    return 3.14 * radius ** 2
在使用注释的时候，需要注意以下问题：

  • 代码本身应尽量自解释，注释仅补充关键逻辑。
  • 修改代码时需同步更新注释，防止误导。
  • 遵循PEP 8规范：注释与代码保持相同缩进，# 后留一个空格。
    （一般不留空格也不会出编译问题，但是编译器可能会给你警告 看着碍眼）

同时如果需要快速添加注释，也可以通过 ctrl+/ 快捷键实现

特殊注释示例

调试注释：临时禁用代码块。

1
# print("调试信息")  # 暂时关闭输出
TODO注释：标记待完成任务。
1
# TODO: 添加异常处理逻辑
文档字符串（Docstring）
模块、类或函数的首行多行注释，可通过 help() 查看。
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
def greet(name):
    """返回问候语  
    参数:  
        name (str): 用户名  
    返回:  
        str: 拼接的问候字符串  
    """
    return f"Hello, {name}!"

print(greet("John")) # 调用函数
help(greet) # 使用 help() 查看函数的注释说明
注释的使用比较简单，通过合理使用注释，能显著提升代码的维护性和协作效率。