[Python 基础课程]注释
什么是注释
在编程语言中，注释是写给程序员自己或他人看的文本。它不会被 Python 解释器执行，也就是说，它不是程序的一部分，它仅仅是提供额外的说明、解释或备注。
注释的作用就像代码中的“便签”或“说明书”，它们帮助我们：
- 理解代码： 解释代码的意图、逻辑或某个部分的复杂性。
- 记录思考： 记下当初为什么选择这种实现方式，或者未来可能需要改进的地方。
- 方便协作： 让你的队友更快地理解你的代码，提高团队的开发效率。
- 调试： 临时禁用部分代码（虽然不推荐作为主要调试手段）。
# 产品经理说必须加这个需求，逻辑如下
# PM insisted this feature, stupid logic below:
Python 中的注释类型
Python 支持两种主要的注释类型：单行注释和多行注释。
单行注释
单行注释使用井号 # 开始， 从 # 符号开始，直到行尾的所有内容都被视为注释。
# 这是一个单行注释，它解释了下面的变量
name = "爱丽丝" # 变量 'name' 存储了用户的姓名# 你可以在代码上方写注释
age = 30# 不推荐使用行尾注释
print(name) # 打印用户的姓名
print(age) # 打印用户的年龄
:::warning
单行注释可以单独占一行，也可以在代码行的末尾添加，但是一般规范的是单行，不推荐在代码行的末尾添加
:::
多行注释
Python 没有专门的多行注释语法。但是，我们通常使用**三引号字符串（Triple-quoted strings）**来充当多行注释。当这些三引号字符串没有被赋值给变量时，它们不会被解释器执行，因此起到了多行注释的作用。
多行注释使用三个单引号 ‘’’ 或三个双引号 “”" 包裹。它适用于需要解释一段代码块、函数或文件的整体功能时。
"""
这是一个多行注释的例子。
它可以跨越多行，用于解释代码的整体功能，
或者提供更详细的说明。
"""'''
你也可以使用三个单引号来创建多行注释。
效果是一样的。
这通常用于模块、类或函数的文档字符串（docstrings），
但也可以作为普通的多行注释使用。
'''def calculate_area(length, width):"""这个函数用于计算矩形的面积。参数:length (int/float): 矩形的长度。width (int/float): 矩形的宽度。返回:int/float: 矩形的面积。"""return length * widthprint(calculate_area(5, 10))
虽然三引号字符串可以充当多行注释，但它们更常用于编写 文档字符串（Docstrings）。文档字符串是紧跟在模块、类或函数定义之后的第一行非空字符串，它用于自动化文档生成工具提取代码说明。
help() 函数可以查看文档字符串：
def example_function():"""这是一个文档字符串。它用于解释函数的功能。"""passhelp(example_function)
# 输出会包含 "这是一个文档字符串。它用于解释函数的功能。"
普通的三引号注释只是为了给人看，而文档字符串则有特殊的地位，可以被工具识别和提取。
函数的文档字符串（函数文档）可以通过可以通过特殊属性 __doc__获取，比如：
def say_hai():"""打印 Hai:return:"""print("Hai")if __name__ == '__main__':print(say_hai.__doc__)
这里将 say_hai 这个函数的函数文档打印出来了。
什么是好的注释
注释不是越多越好，也不是越少越好，关键在于有效性。
- 解释“为什么”，而不是“是什么”：不好的例子：
# 将 x 赋值为 10(代码本身就说明了“是什么”)，好的例子：# 限制最大用户数量，防止服务器过载(解释了为什么做这个操作) - 解释复杂逻辑： 当代码逻辑比较复杂、不易理解时，添加注释来拆解或概括其思路
- 解释非显而易见的变量： 当变量名本身不够清晰时，用注释补充其含义
- TODO 或 FIXME： 标记待办事项或需要修复的问题
# TODO: 这里需要添加用户输入验证
# FIXME: 循环条件可能导致死循环，待修复
- 高层次概括： 在函数或类定义的上方，用多行注释（文档字符串）概括其整体功能。
- 保持更新： 代码修改后，及时更新相关注释，避免误导。过时的注释比没有注释更糟糕。
- 避免冗余： 显而易见的代码不需要注释。
# 不好的注释
# print("Hello") # 打印 "Hello"