Python 代码注释

注释是代码中用于解释和说明的部分，它们不会被 Python 解释器执行。良好的注释是编写可读、可维护代码的关键部分。它能帮助其他开发者（以及未来的你）快速理解代码的意图和逻辑。

Python 主要有两种类型的注释：单行注释和多行注释。

单行注释

单行注释以井号 # 开头，从 # 到该行末尾的所有内容都会被视作注释。

# 这是一个完整的单行注释

name = "Alice"  # 这是一个行内注释，用于解释这个变量的用途

# 下面的代码将打印欢迎信息
print("Hello, " + name)

用途：

• 为单行代码提供简短的解释。
• 在代码块前添加总结性说明。
• 临时禁用一行代码（将其“注释掉”）以进行调试。

# print("This line will not be executed.")

多行注释

严格来说，Python 并没有像其他语言（如 C++ 的 /* ... */）那样的专用多行注释语法。但是，你可以使用多行字符串来达到同样的效果。

多行字符串由三个单引号 ''' 或三个双引号 """ 包裹。如果这个字符串没有被赋值给任何变量，它就会被解释器忽略，从而成为事实上的多行注释。

'''
这是一个多行注释。
它可以跨越任意多行，
非常适合用来写详细的说明。
'''

def add(a, b):
    """
    这也是一个多行注释，但当它出现在函数、类或模块的开头时，
    它有一个特殊的名字：文档字符串 (Docstring)。
    """
    return a + b

print("This code will be executed.")

文档字符串 (Docstrings)

如上例所示，当一个多行字符串是函数、方法、类或模块定义中的第一个语句时，它就变成了该对象的 __doc__ 属性，即文档字符串。

Docstrings 是 Python 的一个重要特性，许多工具（如 help() 函数、IDE、文档生成器）都可以提取并使用它们来自动生成文档。

一个好的 Docstring 示例：

def calculate_area(radius):
    """计算一个圆的面积。

    Args:
        radius (int or float): 圆的半径。

    Returns:
        float: 计算出的圆的面积。
    """
    pi = 3.14159
    return pi * (radius ** 2)

# 你可以通过 help() 函数查看文档字符串
help(calculate_area)

# 或者直接访问 __doc__ 属性
print(calculate_area.__doc__)

注释的最佳实践

1. 注释要清晰、简洁：避免写无意义的注释，如 x = 5 # 将 5 赋值给 x。
2. 注释“为什么”，而不是“是什么”：好的代码本身应该是自解释的（是什么），注释应该用来解释代码背后的复杂逻辑或设计决策（为什么）。
3. 保持注释更新：当你修改代码时，一定要同步更新相关的注释，避免误导。
4. 使用英文编写注释：这是国际通用的最佳实践，便于全球开发者协作。
5. 遵循 PEP 8 风格指南：PEP 8 对注释的格式给出了建议，例如，行内注释 # 前应有两个空格。