别让AI把你的代码注释成废话

cnt++;  // 计数加一

if (voltage < threshold) {  // 如果电压小于阈值
    power_off();
}

/**
 * @brief 处理电机状态
 */
void Motor_Process(void)
{
    switch (motor_state) {
    case MOTOR_STATE_RUN:
        if (fault_flags & MOTOR_FAULT_OVERCURRENT) {
            motor_state = MOTOR_STATE_STOPPING;
        }
        break;
    }
}

/**
 * @brief 处理 RS485 接收事件并推进协议解析状态机。
 *
 * @param port 通信端口索引，取值范围为 0 到 COMM_PORT_MAX - 1。
 * @param event 接收事件，必须来自串口空闲中断或 DMA 完成回调投递。
 *
 * @return 0 表示处理成功；负数表示端口无效、缓冲区异常或协议状态机错误。
 *
 * @note 本函数运行在通信任务上下文，不能在中断中直接调用。
 * @note 只消费环形缓冲区中的完整帧，不负责清空 DMA 原始缓冲区。
 */
int Comm_ProcessRxEvent(uint8_t port, const CommRxEvent_t *event);

/* DMA 写入位置，由串口空闲中断更新；通信任务只读取快照，避免直接改写。 */
static volatile uint16_t s_uart3_dma_write_pos;

/* 电机保护状态机当前状态，只允许 Motor_Task 在任务上下文推进。 */
static MotorProtectState_t s_protect_state;

/* RS485 方向脚释放后需要等待收发器进入接收态，V2.1 板卡实测最小稳定时间约 15us。 */
Delay_Us(20);

/* 零长度接收通常来自空闲中断重复进入，不能推进写指针，否则会破坏环形缓冲区边界。 */
if (rx_len == 0U) {
    s_uart3_zero_len_cnt++;
    return;
}

switch (s_motor_state) {
case MOTOR_STATE_STOPPING:
    /*
     * 先等待 PWM 输出降为 0，再关闭驱动使能。
     * 直接跳到 IDLE 会绕过制动释放流程，可能导致功率桥残余电流未泄放。
     */
    Motor_UpdateStopRamp();
    break;
}

---
name: embedded-code-commenter
description: 当用户要求为嵌入式 C 或 C++ 项目自动补充代码注释、统一注释格式、批量生成函数说明、变量说明、状态机说明、参数返回值说明，并且需要排除开源库、芯片库、自动生成文件和第三方代码时，使用本技能。
---

# 嵌入式代码自动注释

## 目标

为用户自研的嵌入式代码补充少量、准确、统一、可维护的注释。注释重点是设计意图、硬件约束、状态机规则、并发关系、参数单位、返回值含义和边界条件。不要把代码逐行翻译成中文。

## 处理范围

优先处理：

- `App/`
- `User/`
- `BSP/` 中用户手写部分
- `Src/` 中非自动生成部分
- `Inc/` 中用户定义的接口头文件
- 项目中特别标记为业务代码、板级代码、驱动适配代码的文件

必须跳过：

- 芯片厂商库
- RTOS 内核
- 开源组件
- 第三方 SDK
- 自动生成文件
- 已经明确禁止修改的协议文件
- 用户没有授权修改的目录

## 排除规则

遇到以下路径或特征时，不修改文件：

- `CMSIS`
- `HAL_Driver`
- `FreeRTOS`
- `rt-thread`
- `lwip`
- `fatfs`
- `mbedtls`
- `tinyusb`
- `third_party`
- `external`
- `vendor`
- 文件中包含 `DO NOT EDIT`
- 文件中包含 `Generated by`

如果文件来源不确定，先只读分析，不直接修改。

## 注释原则

1. 只给关键代码加注释。
2. 不解释一眼能看懂的语句。
3. 不写空泛评价，例如“提高稳定性”“保证安全运行”，除非说明具体机制。
4. 不改变代码逻辑。
5. 不改变量名、函数名、宏名和文件结构。
6. 不引入新的头文件。
7. 不扩大编译产物。
8. 保持原有编码、缩进和行宽风格。
9. 注释必须能被代码或工程事实支撑。
10. 如果无法判断设计意图，写成待确认注释或不写。

## 必须优先注释的对象

- 对外接口函数。
- 带有硬件时序要求的函数。
- 中断服务函数和回调函数。
- DMA、环形缓冲区、双缓冲相关逻辑。
- 状态机状态和关键迁移条件。
- 安全保护、降额、故障恢复逻辑。
- 协议兼容分支。
- 全局变量、静态变量、跨中断和任务共享的变量。
- 带单位的参数和返回值。
- 魔法数、阈值、延时值、重试次数。

## 函数注释格式

使用以下格式：

```c
/**
 * @brief 用一句话说明函数职责，避免重复函数名。
 *
 * @param 参数名 说明参数含义、单位、范围、是否允许为空。
 * @return 说明返回值含义，特别是错误码和调用方应如何处理。
 *
 * @note 说明调用上下文、硬件约束、并发限制或版本兼容。
 */
```

没有参数时不写 `@param`。没有返回值时不写 `@return`。没有特殊约束时不强行写 `@note`。

## 变量注释格式

全局变量、静态变量和跨上下文共享变量使用行前注释：

```c
/* 说明变量含义、单位、更新者、读取者和并发约束。 */
static volatile uint16_t s_xxx;
```

局部变量只在含义不明显、单位容易误解或涉及边界条件时注释。

## 逻辑注释格式

关键分支、状态迁移、硬件延时和异常处理使用块注释：

```c
/*
 * 说明为什么需要这段逻辑，以及删掉或改错后会导致什么风险。
 */
```

## 状态机注释要求

为状态机补注释时，优先说明：

- 当前状态的意义。
- 允许从哪些状态进入。
- 允许迁移到哪些状态。
- 禁止直接跳转的原因。
- 与硬件动作或安全保护的关系。

## 中断和并发注释要求

遇到中断、DMA、任务共享变量时，必须说明：

- 哪个上下文写。
- 哪个上下文读。
- 是否需要 `volatile`。
- 是否依赖临界区、关中断、互斥锁或原子操作。
- 中断里禁止执行的动作。

## 输出流程

1. 先列出准备处理的文件。
2. 再列出跳过的文件和跳过原因。
3. 对每个文件先识别关键函数、关键变量和关键状态机。
4. 只补必要注释。
5. 修改后汇总新增注释类型。
6. 提醒用户运行编译、静态检查和代码评审。

## 质量检查

完成后检查：

- 是否误改开源库或生成文件。
- 是否出现“该函数用于”“这里判断”“变量赋值”等低价值注释。
- 是否重复解释代码表面含义。
- 是否漏掉参数单位、返回值错误码、调用上下文。
- 是否把不确定的设计意图写成确定事实。
- 是否破坏原有格式。