2.10.注释

# 这是一个单行注释
print("Hello, World!")  # 这是在行尾的注释

# 下面这行代码被注释掉了，不会执行
# print("这行代码不会运行")

# 这是一个多行注释
# 每行前面都加上 # 号
# 这是第三行注释
print("多行注释示例")

"""
这是一个多行注释
使用三个双引号包围
可以写很多行内容
"""
print("三引号注释示例")

'''
也可以使用三个单引号
效果是一样的
'''

# 不好的注释（重复代码）
x = x + 1  # 给x加1

# 好的注释（解释原因）
x = x + 1  # 补偿数组的0-based索引偏移

def calculate_compound_interest(principal, rate, time):
    """
    计算复利
    
    参数:
        principal (float): 本金
        rate (float): 年利率（如0.05表示5%）
        time (float): 时间（年）
    
    返回:
        float: 复利计算后的总金额
    """
    # 复利公式: A = P(1 + r)^t
    amount = principal * (1 + rate) ** time
    return amount

class BankAccount:
    """银行账户类，用于管理个人银行账户操作"""
    
    def __init__(self, account_holder, balance=0):
        """
        初始化银行账户
        
        参数:
            account_holder (str): 账户持有人姓名
            balance (float): 初始余额，默认为0
        """
        self.account_holder = account_holder
        self.balance = balance
    
    def deposit(self, amount):
        """存款操作"""
        if amount > 0:
            self.balance += amount
            return True
        return False

def complex_calculation(a, b, c):
    # 暂时禁用某些计算以便调试
    # result = a * b * c
    # intermediate = result / 2
    
    # 使用简化版本进行测试
    result = a + b + c
    return result

# print("调试信息")  # 临时注释掉调试输出

def is_leap_year(year):
    """
    判断是否为闰年
    
    规则:
    1. 能被4整除但不能被100整除的是闰年
    2. 能被400整除的也是闰年
    """
    # 使用布尔逻辑实现闰年判断规则
    return (year % 4 == 0 and year % 100 != 0) or (year % 400 == 0)

# TODO: 优化这个函数的性能
def slow_function():
    # 当前实现
    pass

# FIXME: 这里有个边界情况需要处理
def buggy_function():
    pass

# HACK: 临时解决方案，需要重构
def temporary_solution():
    pass

def example_function():
    """这是一个示例函数的文档字符串"""
    pass

# 访问文档字符串
print(example_function.__doc__)
# 输出: 这是一个示例函数的文档字符串

# 使用help函数
help(example_function)
# 输出详细的帮助信息

# 不好的例子：注释太啰嗦
x = 5  # 把x设为5
y = 10 # 把y设为10
z = x + y  # 计算x加y的和

# 计算圆的面积（已过时）
# 原来的公式: area = 3.14 * radius * radius
area = math.pi * radius ** 2  # 代码已更新但注释没更新

# 初始化变量
x = 0

# 开始循环
for i in range(10):
    # 打印i
    print(i)

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
文件名: data_processor.py
作者: 张三
创建日期: 2024-01-15
描述: 数据处理模块，用于清洗和分析用户数据
版本: 1.0
"""

# ==================== 配置部分 ====================
DATABASE_URL = "sqlite:///example.db"
MAX_CONNECTIONS = 10

# ==================== 工具函数 ====================
def connect_database():
    """连接数据库"""
    pass

# ==================== 主逻辑 ====================
def main():
    """主函数"""
    pass

def process_data(data):
    """
    处理数据的主函数
    
    DEBUG INFO:
    - 输入数据格式: List[Dict]
    - 输出数据格式: pandas.DataFrame
    - 处理时间: 通常 < 1秒 (1000条记录)
    """
    # 临时调试输出
    # print(f"处理数据长度: {len(data)}")
    # print(f"数据类型: {type(data)}")
    
    # 实际处理逻辑
    processed_data = [item for item in data if item.get('active')]
    return processed_data

# 没有注释的代码（难以理解）
def f(a, b):
    return a if a > b else b

# 有注释的代码（清晰易懂）
def find_maximum(value1, value2):
    """
    返回两个值中的较大值
    
    参数:
        value1: 第一个值
        value2: 第二个值
        
    返回:
        两个值中较大的那个
    """
    return value1 if value1 > value2 else value2