Python 基础知识：注释写法

# /*
# Python 基础知识：注释写法
# --------------------------------------------------------
# 功能：
# 1) 演示单行注释与多行注释写法
# 2) 说明文档字符串（docstring）的用法
# 3) 展示注释在代码阅读与调试中的作用
# */

# ========================================
print("示例一：单行注释")

# 这是单行注释，解释下面的语句
x = 10
print("x =", x)

print("-" * 40)

# ========================================
print("示例二：多行注释 / 块注释（常用三引号）")

"""
这是多行注释的示例
可以写多行说明
在函数、类、模块中也常用于文档字符串
"""
y = 20
print("y =", y)

print("-" * 40)

# ========================================
print("示例三：文档字符串（docstring）")

def add(a, b):
    """
    函数 add 用于计算两个数的和
    参数：
        a - 第一个数
        b - 第二个数
    返回值：
        两数之和
    """
    return a + b

result = add(5, 7)
print("add(5,7) =", result)
print("函数文档：", add.__doc__)

print("-" * 40)

# ========================================
print("示例四：临时注释代码（调试常用）")

# print("这行代码暂时不执行")  # 临时屏蔽

print("调试完成，注释可用于快速屏蔽代码")

print("-" * 40)

# ========================================
# 要点总结：
# 1) 单行注释使用 #，适合简短说明；
# 2) 多行注释常用三引号 """ 或 '''，可用于模块、函数说明；
# 3) docstring 可被 Python 内置函数 help() 访问，用于文档化函数和类；
# 4) 注释不参与程序运行，但对代码可读性、调试和团队协作至关重要；
# 5) 注释应简明扼要、与代码逻辑紧密相关，避免冗长或误导。
# */


# 示例一：单行注释
# x = 10
# ----------------------------------------
# 示例二：多行注释 / 块注释（常用三引号）
# y = 20
# ----------------------------------------
# 示例三：文档字符串（docstring）
# add(5, 7) = 12
# 函数文档：
# 函数
# add
# 用于计算两个数的和
# 参数：
# a - 第一个数
# b - 第二个数
# 返回值：
# 两数之和
#
# ----------------------------------------
# 示例四：临时注释代码（调试常用）
# 调试完成，注释可用于快速屏蔽代码
# ----------------------------------------