# 這是一個(gè)單行注釋
print('Hello, World!')  # 這行打印一句話，這也是注釋

# 下面這行代碼計(jì)算1到100的和
total = 0
for i in range(1, 101):
    total += i  # 累加每一個(gè)數(shù)字
print(total)  # 輸出結(jié)果：5050

print('這條會(huì)執(zhí)行')
# print('這條不會(huì)執(zhí)行，因?yàn)楸蛔⑨尩袅?)
print('這條也會(huì)執(zhí)行')

'''
這是一個(gè)多行注釋
可以跨越多行
Python解釋器會(huì)忽略這些內(nèi)容
'''

"""
這也是一個(gè)多行注釋
用雙引號(hào)也是一樣的效果
可以寫很多行
"""

# 函數(shù)的文檔字符串——這是最正式的用法
def calculate_area(length, width):
    """
    計(jì)算矩形的面積。

    參數(shù)：
        length (float): 矩形的長(zhǎng)度
        width (float): 矩形的寬度

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

# 代碼頂部的模塊說明
'''
模塊名：用戶管理
功能：處理用戶的注冊(cè)、登錄、信息修改等操作
作者：張三
日期：2025-05-30
版本：v1.0
'''

# 臨時(shí)注釋掉一大段代碼
'''
print('這段代碼暫時(shí)不需要執(zhí)行')
print('先用三個(gè)引號(hào)把它包起來')
print('等需要的時(shí)候再解開')
'''

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

    Args:
        name: 被問候的人的名字
        greeting: 問候語，默認(rèn)為"你好"

    Returns:
        str: 完整的問候語字符串

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


# 文檔字符串可以通過__doc__屬性被程序訪問
print(greet.__doc__)
# 輸出上面寫的整個(gè)文檔

# 也可以用help()函數(shù)查看
help(greet)
# 輸出格式化的文檔

# 使用埃拉托斯特尼篩法找出所有質(zhì)數(shù)
def sieve_of_eratosthenes(n):
    is_prime = [True] * (n + 1)
    is_prime[0] = is_prime[1] = False

    # 只需要檢查到sqrt(n)，因?yàn)槿绻鹡是合數(shù)，
    # 它必定有一個(gè)因子小于等于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]]

# 注意：這個(gè)函數(shù)假設(shè)輸入列表已按升序排列
# 如果列表未排序，返回的結(jié)果將是錯(cuò)誤的
def binary_search(sorted_list, target):
    # ... 二分查找的實(shí)現(xiàn)

# 在Windows上，文件路徑中的反斜杠需要轉(zhuǎn)義
# 使用os.path.join可以避免平臺(tái)差異
import os
file_path = os.path.join('data', 'users', 'info.csv')

# TODO: 這里的錯(cuò)誤處理需要完善，目前只在理想情況下工作
# FIXME: 當(dāng)用戶名為空時(shí)會(huì)崩潰，需要添加空值檢查
# HACK: 這是一個(gè)臨時(shí)方案，等后端接口好了之后要重構(gòu)

# 不需要注釋
name = '小明'  # 設(shè)置名字為小明
age = 20       # 設(shè)置年齡為20

# 上面的注釋完全是廢話，代碼已經(jīng)說得很清楚了

# 不需要注釋——函數(shù)名和變量名已經(jīng)說明了一切
def calculate_average_score(scores):
    total = sum(scores)
    count = len(scores)
    return total / count

# ? 一大段需要注釋的復(fù)雜代碼
def process_order(order):
    # 首先驗(yàn)證訂單狀態(tài)，必須是"待發(fā)貨"
    # 然后檢查庫(kù)存是否充足
    # 如果庫(kù)存足夠，扣減庫(kù)存
    # 最后更新訂單狀態(tài)為"已發(fā)貨"
    # ... 20行代碼
    pass

# ? 拆分為小函數(shù)，函數(shù)名本身就是最好的注釋
def process_order(order):
    validate_order(order)
    check_inventory(order)
    deduct_inventory(order)
    update_order_status(order, '已發(fā)貨')

# ? 壞注釋：重復(fù)代碼
# 遍歷員工列表
for employee in employees:
    # 計(jì)算工資
    salary = employee.hours * employee.hourly_rate
    # 打印工資
    print(salary)

# ? 好注釋：解釋背后的意圖
for employee in employees:
    salary = employee.hours * employee.hourly_rate
    # 根據(jù)公司政策，加班時(shí)間按1.5倍計(jì)算
    if employee.hours > 40:
        overtime_hours = employee.hours - 40
        salary += overtime_hours * employee.hourly_rate * 0.5
    print(salary)

# ? 危險(xiǎn)的過時(shí)注釋
def calculate_tax(income):
    # 使用2018年的稅率（實(shí)際上2025年已經(jīng)改了?。?
    if income < 5000:
        return 0
    elif income < 8000:
        return income * 0.03
    # ...

# ? 更好的做法：用清楚的代碼代替注釋
# 稅率表直接來自數(shù)據(jù)，代碼本身說明了邏輯
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

# 個(gè)人學(xué)習(xí)項(xiàng)目——中文注釋完全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   # 目標(biāo)在右半部分
        else:
            right = mid - 1  # 目標(biāo)在左半部分
    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))

"""
學(xué)生成績(jī)篩選程序
功能：從學(xué)生成績(jī)字典中篩選出及格（>=60分）的學(xué)生名單
"""


def filter_by_criteria(data_dict, check_function):
    """
    根據(jù)指定的篩選條件，從字典中篩選出符合條件的鍵。

    參數(shù)：
        data_dict (dict): 待篩選的字典，鍵為學(xué)生名，值為成績(jī)
        check_function (callable): 篩選函數(shù)，接受一個(gè)值，返回True/False

    返回：
        list: 符合條件的鍵（學(xué)生名）列表

    示例：
        >>> scores = {'小明': 85, '小紅': 42}
        >>> filter_by_criteria(scores, lambda x: x >= 60)
        ['小明']
    """
    passed_keys = []  # 存儲(chǔ)符合條件的學(xué)生名
    for key, value in data_dict.items():
        if check_function(value):
            passed_keys.append(key)  # 該學(xué)生成績(jī)符合條件，加入結(jié)果
    return passed_keys


# 學(xué)生成績(jī)數(shù)據(jù)
student_scores = {
    '小明': 85,
    '小紅': 42,
    '小剛': 96,
    '小麗': 58,
    '小華': 73
}

# 篩選條件：成績(jī)大于等于60分（及格線）
def is_passing(score):
    return score >= 60

# 執(zhí)行篩選并輸出結(jié)果
passing_students = filter_by_criteria(student_scores, is_passing)
print(f'及格的學(xué)生有：{passing_students}')
print(f'及格人數(shù)：{len(passing_students)}人')
print(f'不及格人數(shù)：{len(student_scores) - len(passing_students)}人')

def complex_calculation(data):
    # 第一步：數(shù)據(jù)清洗
    cleaned_data = clean_data(data)
    print(f'清洗后數(shù)據(jù)條數(shù)：{len(cleaned_data)}')

    # 第二步：數(shù)據(jù)轉(zhuǎn)換（懷疑這里有bug，先注釋掉后面，只看前面的輸出）
    # transformed_data = transform_data(cleaned_data)
    # print(f'轉(zhuǎn)換后數(shù)據(jù)條數(shù)：{len(transformed_data)}')

    # 第三步：計(jì)算
    # result = calculate(transformed_data)
    # return result

    # 暫時(shí)返回None，等排查完bug再恢復(fù)
    return None

# 寫法一：使用列表推導(dǎo)式
# squared = [x**2 for x in range(10)]

# 寫法二：使用map函數(shù)
# squared = list(map(lambda x: x**2, range(10)))

# 寫法三：傳統(tǒng)for循環(huán)——當(dāng)前采用這種寫法，最易讀
squared = []
for x in range(10):
    squared.append(x ** 2)

print(squared)