代码注释：顶尖程序员的必修课，而非可选项优雅草卓伊凡

/*
 * 内存屏障：确保在修改指针前，
 * 所有数据对DMA引擎可见
 * @param addr 必须4KB对齐
 */
void set_dma_addr(void *addr) {
    // 详见ARM手册B2.3.4节
    asm volatile("dmb ish" ::: "memory");
}

# 坏例子：某未注释的加密函数
def f(x): 
    return ((x >> 2) ^ 0xDEADBEEF) & 0xFF

# 新同事被迫"考古"：
# 1. 为什么要右移2位？
# 2. 魔数0xDEADBEEF的由来？
# 3. 为什么最后取8位？

// 根据FDA 21 CFR Part 11规范：
// - 必须记录操作者
// - 审计日志保留10年
void saveMedicalRecord() {...}

# 使用曼哈顿距离而非欧式距离：
# - 避免浮点运算（性能敏感场景）
# - 客户明确要求整数输出
def distance(x1, y1, x2, y2):
    return abs(x1-x2) + abs(y1-y2)

/* 2022-03漏洞修复：
 * - 原方案会溢出（CVE-2022-1234）
 * - 改用SafeInt库防护
 */
int calc_buffer_size() {...}

// 坏注释（冗余）
let count = 0; // 设置count为0

// 好代码（自解释）
let activeUserCount = 0;

def calculate_tax(income):
    # [AI自动生成注释]
    """计算所得税
    Args:
        income (float): 年收入（单位：万元）
    Returns:
        float: 应缴税额（适用2023年税率表）
    """

/** 格式化日期为YYYY-MM-DD */
function formatDate(d: Date) {...}

/**
 * struct device - 核心设备模型
 * @name: 设备名称（显示给用户）
 * @power: 当前电源状态（见POWER_*常量）
 * @lock: 防止并发操作的自旋锁
 */
struct device {
    char *name;
    int power;
    spinlock_t lock;
};

// 自解释？其实隐藏业务知识
if (employee.age > 65 && employee.years > 30) {...}

// 加上注释才完整
// 根据《劳动法》第45条：
// - 65岁以上且工龄超30年可提前退休
if (employee.age > 65 && employee.years > 30) {...}

# .github/workflows/comment-check.yml
- name: 验证注释
  run: |
    grep -r "TODO:" src/ && exit 1 || exit 0

def add(a, b):
    """返回两数之和
    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    """
    return a + b

void ProcessData() {
    var x = GetData().Where(d => d > 10);
    Save(x.Take(20));
}

/// 处理传感器数据并存储：
/// 1. 过滤异常值（<10为硬件噪声）
/// 2. 最多保存20条（避免内存溢出）
/// 注意：需在UTC时间整点调用（见ISSUE#123）
void ProcessSensorData() {
    var validReadings = GetRawData().Where(r => r > 10);
    SaveToDatabase(validReadings.Take(20));
}