Python入门指南之代码注释的三种写法详解

# 这是一个单行注释
print('Hello, World!')  # 这行打印一句话，这也是注释

# 下面这行代码计算1到100的和
total = 0
for i in range(1, 101):
    total += i  # 累加每一个数字
print(total)  # 输出结果：5050

print('这条会执行')
# print('这条不会执行，因为被注释掉了')
print('这条也会执行')

'''
这是一个多行注释
可以跨越多行
Python解释器会忽略这些内容
'''

"""
这也是一个多行注释
用双引号也是一样的效果
可以写很多行
"""

# 函数的文档字符串——这是最正式的用法
def calculate_area(length, width):
    """
    计算矩形的面积。

    参数：
        length (float): 矩形的长度
        width (float): 矩形的宽度

    返回：
        float: 矩形的面积
    """
    return length * width

# 代码顶部的模块说明
'''
模块名：用户管理
功能：处理用户的注册、登录、信息修改等操作
作者：张三
日期：2025-05-30
版本：v1.0
'''

# 临时注释掉一大段代码
'''
print('这段代码暂时不需要执行')
print('先用三个引号把它包起来')
print('等需要的时候再解开')
'''

def greet(name, greeting='你好'):
    """向指定的人打招呼。

    Args:
        name: 被问候的人的名字
        greeting: 问候语，默认为"你好"

    Returns:
        str: 完整的问候语字符串

    Examples:
        >>> greet('小明')
        '你好，小明！'
        >>> greet('小红', '嗨')
        '嗨，小红！'
    """
    return f'{greeting}，{name}！'


# 文档字符串可以通过__doc__属性被程序访问
print(greet.__doc__)
# 输出上面写的整个文档

# 也可以用help()函数查看
help(greet)
# 输出格式化的文档

# 使用埃拉托斯特尼筛法找出所有质数
def sieve_of_eratosthenes(n):
    is_prime = [True] * (n + 1)
    is_prime[0] = is_prime[1] = False

    # 只需要检查到sqrt(n)，因为如果n是合数，
    # 它必定有一个因子小于等于sqrt(n)
    for i in range(2, int(n ** 0.5) + 1):
        if is_prime[i]:
            for j in range(i * i, n + 1, i):
                is_prime[j] = False

    return [i for i in range(2, n + 1) if is_prime[i]]

# 注意：这个函数假设输入列表已按升序排列
# 如果列表未排序，返回的结果将是错误的
def binary_search(sorted_list, target):
    # ... 二分查找的实现

# 在Windows上，文件路径中的反斜杠需要转义
# 使用os.path.join可以避免平台差异
import os
file_path = os.path.join('data', 'users', 'info.csv')

# TODO: 这里的错误处理需要完善，目前只在理想情况下工作
# FIXME: 当用户名为空时会崩溃，需要添加空值检查
# HACK: 这是一个临时方案，等后端接口好了之后要重构

# 不需要注释
name = '小明'  # 设置名字为小明
age = 20       # 设置年龄为20

# 上面的注释完全是废话，代码已经说得很清楚了

# 不需要注释——函数名和变量名已经说明了一切
def calculate_average_score(scores):
    total = sum(scores)
    count = len(scores)
    return total / count

# ❌ 一大段需要注释的复杂代码
def process_order(order):
    # 首先验证订单状态，必须是"待发货"
    # 然后检查库存是否充足
    # 如果库存足够，扣减库存
    # 最后更新订单状态为"已发货"
    # ... 20行代码
    pass

# ✅ 拆分为小函数，函数名本身就是最好的注释
def process_order(order):
    validate_order(order)
    check_inventory(order)
    deduct_inventory(order)
    update_order_status(order, '已发货')

# ❌ 坏注释：重复代码
# 遍历员工列表
for employee in employees:
    # 计算工资
    salary = employee.hours * employee.hourly_rate
    # 打印工资
    print(salary)

# ✅ 好注释：解释背后的意图
for employee in employees:
    salary = employee.hours * employee.hourly_rate
    # 根据公司政策，加班时间按1.5倍计算
    if employee.hours > 40:
        overtime_hours = employee.hours - 40
        salary += overtime_hours * employee.hourly_rate * 0.5
    print(salary)

# ❌ 危险的过时注释
def calculate_tax(income):
    # 使用2018年的税率（实际上2025年已经改了！）
    if income < 5000:
        return 0
    elif income < 8000:
        return income * 0.03
    # ...

# ✅ 更好的做法：用清楚的代码代替注释
# 税率表直接来自数据，代码本身说明了逻辑
TAX_BRACKETS_2025 = [
    (0, 5000, 0),
    (5000, 8000, 0.03),
    (8000, 17000, 0.10),
    # ...
]

def calculate_tax(income):
    for lower, upper, rate in TAX_BRACKETS_2025:
        if lower <= income < upper:
            return (income - lower) * rate

# 个人学习项目——中文注释完全OK
def binary_search(arr, target):
    """二分查找算法"""
    left, right = 0, len(arr) - 1
    while left <= right:
        mid = (left + right) // 2
        if arr[mid] == target:
            return mid   # 找到了
        elif arr[mid] < target:
            left = mid + 1   # 目标在右半部分
        else:
            right = mid - 1  # 目标在左半部分
    return -1  # 没找到

def f(d, p):
    r = []
    for k, v in d.items():
        if p(v):
            r.append(k)
    return r

data = {'a': 85, 'b': 42, 'c': 96, 'd': 58, 'e': 73}
print(f(data, lambda x: x >= 60))

"""
学生成绩筛选程序
功能：从学生成绩字典中筛选出及格（>=60分）的学生名单
"""


def filter_by_criteria(data_dict, check_function):
    """
    根据指定的筛选条件，从字典中筛选出符合条件的键。

    参数：
        data_dict (dict): 待筛选的字典，键为学生名，值为成绩
        check_function (callable): 筛选函数，接受一个值，返回True/False

    返回：
        list: 符合条件的键（学生名）列表

    示例：
        >>> scores = {'小明': 85, '小红': 42}
        >>> filter_by_criteria(scores, lambda x: x >= 60)
        ['小明']
    """
    passed_keys = []  # 存储符合条件的学生名
    for key, value in data_dict.items():
        if check_function(value):
            passed_keys.append(key)  # 该学生成绩符合条件，加入结果
    return passed_keys


# 学生成绩数据
student_scores = {
    '小明': 85,
    '小红': 42,
    '小刚': 96,
    '小丽': 58,
    '小华': 73
}

# 筛选条件：成绩大于等于60分（及格线）
def is_passing(score):
    return score >= 60

# 执行筛选并输出结果
passing_students = filter_by_criteria(student_scores, is_passing)
print(f'及格的学生有：{passing_students}')
print(f'及格人数：{len(passing_students)}人')
print(f'不及格人数：{len(student_scores) - len(passing_students)}人')

def complex_calculation(data):
    # 第一步：数据清洗
    cleaned_data = clean_data(data)
    print(f'清洗后数据条数：{len(cleaned_data)}')

    # 第二步：数据转换（怀疑这里有bug，先注释掉后面，只看前面的输出）
    # transformed_data = transform_data(cleaned_data)
    # print(f'转换后数据条数：{len(transformed_data)}')

    # 第三步：计算
    # result = calculate(transformed_data)
    # return result

    # 暂时返回None，等排查完bug再恢复
    return None

# 写法一：使用列表推导式
# squared = [x**2 for x in range(10)]

# 写法二：使用map函数
# squared = list(map(lambda x: x**2, range(10)))

# 写法三：传统for循环——当前采用这种写法，最易读
squared = []
for x in range(10):
    squared.append(x ** 2)

print(squared)