EV-Embedded-Control-System/.trae/skills/chinese-commenter/SKILL.md

name	description
chinese-commenter	Adds detailed Chinese comments to C source files in a project. Invoke when user wants to add Chinese documentation to their embedded project code.

Chinese Commenter Skill

Overview

This skill automatically adds detailed Chinese comments to C source files in an embedded project. It enhances code readability and maintainability by adding:

• Function descriptions and parameter explanations
• Variable and struct comments
• Section headers for better organization
• Technical notes and usage instructions

Supported File Types

• .c - C source files
• .h - Header files

Usage Guidelines

1. Basic Usage

To add Chinese comments to a single file:

1. Use Read tool to get the file content:
   Read("d:/project/src/main.c")

2. Analyze the code structure and identify:
   - Functions and their purposes
   - Key variables and data structures
   - Code sections and logical blocks

3. Use Edit tool to add comments:
   Edit("d:/project/src/main.c", "old_code", "new_code_with_comments")

2. Processing Multiple Files

To process all files in a project:

1. Use Glob to find all C files:
   Glob("**/*.c", "d:/project/src")

2. Iterate through each file and add comments:
   For each file:
   - Read the file content
   - Add Chinese comments to functions, variables, and sections
   - Use Edit tool to apply changes

3. Comment Standards

Follow these commenting standards:

File Header

/**
  **************************************************************************
  * @file     filename.c
  * @brief    文件功能描述
  * @details  详细说明文件的用途和实现
  **************************************************************************
  */

Function Comments

/**
  * @brief  函数功能描述
  * @param  param1: 参数1说明
  * @param  param2: 参数2说明
  * @retval 返回值说明
  * @note   注意事项
  */

Section Headers

/* ==================== 功能模块名称 ==================== */

Variable Comments

uint32_t counter;           /* 计数器：记录某种状态 */

Example Workflow

Step 1: Explore Project Structure

LS("d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src")
Glob("**/*.c", "d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src")

Step 2: Process Main File

Read("d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src/main.c")

Edit("d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src/main.c",
     "int main(void)",
     "/**\n  * @brief  主函数入口\n  * @param  none\n  * @retval none\n  */\nint main(void)")

Step 3: Process Driver Files

Read("d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src/wk_can.c")

Edit("d:/Trae_space/嵌入式开发/byd_qin_ev 1.4/project/src/wk_can.c",
     "void wk_can1_init(void)",
     "/**\n  * @brief  CAN1初始化函数\n  * @param  none\n  * @retval none\n  * @note   CAN1工作在监听模式，用于侦听车辆CAN总线数据\n  */\nvoid wk_can1_init(void)")

Best Practices

1. Understand Code First: Always read the file completely before adding comments
2. Be Descriptive: Explain why as well as what the code does
3. Follow Standards: Maintain consistent comment style throughout the project
4. Update Regularly: Keep comments in sync when code changes
5. Avoid Redundancy: Don't repeat what the code already clearly shows
6. Use Chinese: Write comments in clear, concise Chinese

Common Patterns

CAN Driver Comments

/* ==================== GPIO配置 ==================== */
/* ==================== CAN基础配置 ==================== */
/* ==================== 波特率配置 ==================== */
/* ==================== 过滤器配置 ==================== */
/* ==================== 中断配置 ==================== */

FreeRTOS Task Comments

/**
  * @brief  任务函数名称
  * @param  pvParameters: 任务参数
  * @retval none
  * @note   任务优先级：X，堆栈大小：Y字节
  */

System Initialization Comments

/**
  * @brief  系统初始化函数
  * @param  none
  * @retval none
  * @details 执行顺序：
  *          1. 时钟配置
  *          2. 外设初始化
  *          3. 中断配置
  *          4. 应用任务启动
  */

When to Invoke This Skill

• User asks to add comments to C code
• User wants to improve code documentation
• User needs to document an embedded project
• Before sharing code with team members
• When preparing code for review or handover

Notes

• This skill works best with embedded C projects
• Always preserve the original code functionality
• Comments should enhance, not obscure, the code
• Use appropriate technical terminology in Chinese
• Keep comments concise but informative