2. 文件头注释：版权信息、文件功能描述、修改历史记录的标准化写法

好，咱们直接进入正题。文件头注释，说白了就是一个文件的「身份证」。你想想看，一个项目动辄几百个源文件，三年后你回头再看，或者新同事接手，如果没有这个头注释，那真是两眼一抹黑。

我个人习惯，每个 .c 和 .h 文件的开头，必须有一个标准化的文件头。这不是形式主义，这是给自己和团队省时间。我在项目中遇到过最惨的一次，一个驱动文件没有写修改历史，结果出了 bug 排查了三天，最后发现是半年前某位同事改了一行代码忘了通知大家。嗯，从那以后，我对文件头的要求就变得非常严格。

2.1 版权信息：别让你的代码「裸奔」

版权信息不是可有可无的。尤其是商业项目，或者你打算开源，这一块必须写清楚。说白了，这就是你的代码的「所有权声明」。

标准格式长这样：

/*
 * Copyright (c) 2024, Your Company Name
 * All rights reserved.
 *
 * 文件名称: led_driver.c
 * 文件标识: SEELE-LED-DRV-001
 * 摘    要: LED驱动模块，负责板载LED的初始化与控制
 */

这里有几个要点：

• 年份：写创建年份，后续修改不要改这个年份。如果跨年修改，可以在后面追加，比如 "2023-2024"。
• 公司或作者：写清楚归属。个人项目写你的名字或昵称。
• 文件标识：这个很多人会忽略。我建议大项目一定要有，方便文档管理和追溯。

2.2 文件功能描述：一句话说清楚「它干嘛的」

功能描述不要写太长。我见过有人写了一大段，结果全是废话。标准做法是：

/*
 * 功能描述: 提供LED的初始化、亮灭控制及状态查询接口。
 *            支持PWM调光，适配GPIO0~GPIO3四个通道。
 */

为什么要这样写？因为别人看你的代码，第一眼就想知道：这个文件我能不能用？怎么用？

我曾经接手过一个项目，一个叫 "utils.c" 的文件，里面塞了串口、定时器、CRC校验、还有几个不知道干嘛的函数。没有功能描述，全靠猜。你想想看，这得多痛苦。

所以，功能描述要包含：

• 核心功能：这个模块是做什么的？
• 关键特性：比如支持哪些接口、有哪些特殊能力。
• 依赖关系：如果依赖其他模块，最好也提一句。

2.3 修改历史记录：代码的「黑匣子」

修改历史记录，这是文件头里最重要的部分，也是最容易被忽视的部分。为什么重要？因为代码是活的，今天写完明天可能就要改。没有历史记录，你根本不知道这段代码经历过什么。

标准格式我推荐用表格形式，清晰明了：

/*
 * 修改历史：
 * 版本号  日期      作者     修改内容
 * ------+---------+--------+----------------------------------
 * V1.0   2024-01-10 张三   初始版本
 * V1.1   2024-03-15 李四   修复PWM频率计算错误，增加异常处理
 * V1.2   2024-06-20 王五   重构初始化流程，兼容新硬件版本
 */

这里有几个硬性要求：

• 版本号：必须递增，不能跳号。V1.0, V1.1, V2.0 这样。
• 日期：用 ISO 标准格式 YYYY-MM-DD，别用 2024/1/10 这种乱七八糟的格式。
• 作者：写真实姓名或工号，别写昵称。
• 修改内容：简明扼要，但必须说清楚「为什么改」和「改了什么」。

2.4 完整的文件头示例

好了，我们把上面这些拼起来，就是一个完整的标准化文件头：

/*
 * Copyright (c) 2024, Your Company Name
 * All rights reserved.
 *
 * 文件名称: led_driver.c
 * 文件标识: SEELE-LED-DRV-001
 * 摘    要: LED驱动模块，负责板载LED的初始化与控制
 *
 * 功能描述: 提供LED的初始化、亮灭控制及状态查询接口。
 *            支持PWM调光，适配GPIO0~GPIO3四个通道。
 *
 * 修改历史：
 * 版本号  日期      作者     修改内容
 * ------+---------+--------+----------------------------------
 * V1.0   2024-01-10 张三   初始版本
 * V1.1   2024-03-15 李四   修复PWM频率计算错误，增加异常处理
 * V1.2   2024-06-20 王五   重构初始化流程，兼容新硬件版本
 */

这个模板，我用了快十年。不管在哪个公司，哪个项目，我都是这套格式。为什么？因为它够用，而且团队里所有人都能一眼看懂。

2.5 几个容易踩的坑

最后，我再说几个实际项目中容易犯的错误：

• 头注释和代码之间没有空行：这会让阅读体验很差。建议头注释结束后空一行，再写 #include 或代码。
• 修改历史只追加不删除：永远不要删除旧的修改记录。那是历史，删了就没了。
• 版本号和 Git 提交号混淆：文件头里的版本号是业务版本，Git 的 commit hash 是技术版本。两者都要保留，但别混为一谈。
• 头注释里写「本文件禁止修改」：这种话我见过好几次。代码是活的，没有不能改的文件。真要禁止修改，应该在权限上控制，而不是写在注释里。

嗯，文件头注释就这些。说白了，它就是一份微型文档。写好了，能省下无数沟通成本。写不好，那就是一堆占地方的废话。你自己选吧。