4、文件头注释规范：版权信息、作者、日期、文件描述、修改历史的标准格式

说到文件头注释，我见过太多团队在这个问题上栽跟头了。有的项目头注释写得比正文还长，有的干脆啥也不写，过三个月连自己写的代码都看不懂。说白了，文件头注释就是给这个文件办的一张「身份证」，既要信息完整，又不能啰嗦。

4.1 为什么需要标准格式？

你想想看，一个嵌入式项目少说几十个文件，多则上千个。没有统一格式，每个人按自己喜好写，那画面太美我不敢看。我曾经接手过一个老项目，同一个目录下三种注释风格并存，有的用中文，有的用英文，有的干脆是拼音缩写……嗯，那段时间我每天的工作就是猜谜。

标准格式的好处很明显：

• 可追溯：出了问题能快速找到责任人
• 可维护：新人接手时能快速了解文件背景
• 可自动化：统一的格式方便脚本提取信息

4.2 标准文件头模板

我个人习惯用下面这个模板，经过多个项目验证，信息够用又不冗余：

/******************************************************************************
 * @file        : driver_uart.c
 * @brief       : UART驱动模块 - 支持波特率9600~115200
 * @author      : 张三 <zhangsan@company.com>
 * @date        : 2024-01-15
 * @version     : v2.1.0
 * @copyright   : Copyright (c) 2024, 某某科技有限公司
 * @note        : 本模块依赖hal_uart.c中的底层接口
 * @attention   : 使用前请确认硬件引脚配置正确
 *
 * 修改历史：
 * <Date>       <Version>  <Author>   <Description>
 * 2024-01-15    v2.1.0     张三       重构波特率计算逻辑
 * 2023-11-20    v2.0.0     李四       新增DMA传输模式
 * 2023-06-01    v1.0.0     张三       初始版本
 ******************************************************************************/

4.3 修改历史的正确写法

这块是很多人容易忽略的。修改历史不是流水账，而是给后人看的「决策记录」。我在项目中遇到过这样的情况：一个bug查了两天，最后发现是三个月前某次修改引入的，但修改历史里只写了「优化代码」四个字……你说气不气人？

好的修改历史应该包含：

• 日期：精确到日即可，不需要时分秒
• 版本号：每次修改都要升版本，哪怕只是改了个注释
• 作者：谁改的谁负责
• 描述：说清楚「为什么改」而不是「改了哪里」

4.4 版权信息的注意事项

版权声明这块，很多初创团队不太在意。但我建议从一开始就规范起来，不然后面扯皮的事情多着呢。我曾经见过一个项目，离职员工把代码带走，因为没有版权声明，公司连维权都困难。

标准的版权声明格式：

 * @copyright   : Copyright (c) 2024, 某某科技有限公司
 * @license     : 本软件采用MIT协议开源，详见LICENSE文件

4.5 不同文件类型的头注释差异

头文件（.h）和源文件（.c）的头注释略有不同，我一般这样区分：

字段	.h 文件	.c 文件
@brief	描述对外接口的功能	描述内部实现细节
@note	标注使用注意事项	标注算法或逻辑说明
@attention	强调线程安全等约束	强调硬件依赖等约束

举个例子，头文件的注释会更侧重「使用者视角」：

 * @brief       : UART驱动对外接口 - 提供初始化、发送、接收三个函数
 * @note        : 所有函数均为阻塞模式，如需非阻塞请使用DMA版本
 * @attention   : 调用UART_Init前必须先使能GPIO时钟

而源文件的注释则更侧重「维护者视角」：

 * @brief       : UART驱动实现 - 基于STM32 HAL库封装
 * @note        : 波特率计算采用整数分频方式，误差控制在±2%以内
 * @attention   : 本模块依赖hal_uart.c，请确保该文件已包含在工程中

4.6 避坑指南

最后分享几个我踩过的坑：

• 不要用中文写注释：不是我看不起中文，而是不同IDE的编码支持不一样，UTF-8和GBK混用会让你欲哭无泪
• 日期格式要统一：我曾经见过同一个文件里「2024.1.15」「2024-01-15」「2024年1月15日」三种格式并存
• 版本号别乱跳：从v1.0.0直接跳到v2.0.0，中间没有任何记录，这种操作我见过不止一次
• 邮箱要有效：写个离职员工的邮箱，等于没写