4. 文件组织规范：一个模块一个文件的原则，文件头注释模板
做数字IC设计这些年，我见过最乱的代码仓库是什么样的？
一个文件里塞了七八个模块，找某个信号定义得翻三页。更夸张的是，有人把整个芯片的代码都写在一个.v文件里——编译一次要等十分钟。嗯，这其实是个很要命的问题。
4.1 为什么坚持“一个模块一个文件”？
说白了，这是工程化思维的第一步。你想想看，如果每个模块都有自己的独立文件，带来的好处是实实在在的：
- 定位快：看到文件名就知道里面是什么模块，不用猜
- 复用方便：想用某个模块，直接拷贝一个文件就行
- 版本管理清晰：git diff 只看一个模块的改动，review 代码时省心
- 编译加速：增量编译时只重新编译改动的文件
核心原则：一个 .v 或 .sv 文件，只包含一个 module。文件名必须与模块名完全一致。
我在项目中遇到过一位同事，他把所有模块都写在同一个文件里。后来要单独验证其中一个子模块，得先把那个模块从大文件里抠出来，再写 testbench。折腾了大半天。从那以后，我们团队就立了规矩：一个模块一个文件，谁违反谁请下午茶。
4.2 文件命名规范
文件名怎么起？我个人习惯用这样的格式：
模块名_版本号.sv // 标准格式
uart_top_v1.0.sv
spi_master_v2.1.sv
ahb_ram_ctrl_v1.0.sv如果模块有多个版本，或者需要区分不同工艺，可以加后缀：
uart_top_v1.0_tsmc28.sv // 28nm工艺版本
uart_top_v1.0_smic55.sv // 55nm工艺版本注意：文件名不要用中文，不要用空格，不要用特殊字符。下划线和小写字母是最安全的组合。
4.3 文件头注释模板——我用了十年的模板
文件头注释，很多人觉得是形式主义。但说实话，当项目做到第三年，代码量超过十万行时，一个规范的文件头能帮你省下大量时间。
下面这个模板，是我从第一份工作开始就用的，后来不断优化，现在分享给你：
// ============================================================================
// 模块名称 : uart_top
// 功能描述 : UART顶层模块，集成发送和接收通路
// 支持波特率9600/19200/115200，可配置数据位、停止位、校验位
// 作者 : Zhang San
// 创建日期 : 2024-01-15
// 版本号 : v1.0
// 修改记录 :
// v1.0 - 2024-01-15 - 初始版本
// v1.1 - 2024-03-20 - 修复接收FIFO溢出bug
// v1.2 - 2024-06-10 - 增加低功耗门控时钟
// 依赖模块 : uart_tx, uart_rx, uart_baud_gen
// 时钟域 : clk_50m (50MHz), clk_uart (1.8432MHz)
// 复位方式 : 异步复位，高电平有效
// 接口协议 : APB slave interface
// 特殊说明 : 接收FIFO深度为16，满标志为高时停止接收
// ============================================================================我的小技巧：修改记录里一定要写清楚改了啥、为什么改。我曾经因为没写修改原因，三个月后回头看自己的代码，完全想不通当时为什么要加那个逻辑。嗯，从那以后我每条修改记录都写得很详细。
4.4 文件头里必须包含的信息
根据我多年的经验，文件头至少要包含以下几类信息：
| 信息类别 | 必须包含 | 可选包含 |
|---|---|---|
| 标识信息 | 模块名称、版本号 | 项目名称、公司名称 |
| 功能描述 | 模块做什么、主要特性 | 性能指标、面积约束 |
| 版本历史 | 修改日期、修改内容 | 修改人、评审人 |
| 依赖关系 | 依赖的子模块 | 依赖的IP、库文件 |
| 接口信息 | 时钟域、复位方式 | 时序约束、接口协议 |
4.5 文件组织的避坑指南
我曾经犯过一个错误：把多个版本的模块放在同一个目录下，文件名只差一个版本号。结果有一次综合时，工具抓错了版本，导致整个芯片的时序全乱了。排查了两天才找到原因。
所以我现在建议：
- 不同版本的模块放在不同目录：比如 rtl_v1.0/、rtl_v2.0/
- 不要用“最终版”“最终版2”这种命名：用版本号管理，清晰又专业
- 废弃的模块文件要及时归档或删除：留在仓库里只会让人困惑
血的教训：永远不要在文件名里写“final”。我见过一个项目，文件名从“final”改到“final_real”再到“final_real_v2”，最后没人知道哪个才是真的最终版。
4.6 本章知识体系
下面这张图，帮你理清文件组织的核心逻辑：
这张图把文件组织的四个关键维度串起来了。你写代码时，对照着这张图检查一遍，基本不会出大问题。
总结一下：文件组织看似是小事，但它决定了你的代码能不能被团队其他人快速理解和使用。一个模块一个文件，配上规范的文件头注释，这是专业工程师的基本素养。
可可精品资料库