第四章：文件与模块结构规范
好，咱们今天聊聊文件与模块结构。这话题听起来有点「行政化」，对吧？但说实话，我见过太多项目因为文件结构混乱，最后 debug 到崩溃。嗯，一个文件里塞了三四个模块，端口列表排得跟迷宫似的——这种代码，谁接手谁想哭。
一、一个文件一个模块原则
这个原则，说白了就是：一个 .v 文件里，只放一个 module。听起来简单，但很多人不遵守。
我刚开始做项目时，有个老同事特别喜欢把顶层模块和子模块写在一个文件里。当时觉得挺方便，不用切文件。结果项目做到一半，版本管理工具 diff 出来的全是乱码——因为一个文件改了，你不知道改的是顶层还是子模块。后来我接手他的代码，光是拆分文件就花了两天。
为什么要坚持「一个文件一个模块」？
- 版本管理清晰：git diff 能精确告诉你哪个模块改了
- 复用方便：想用某个模块，直接复制文件就行，不用从大文件里抠
- 综合工具友好：有些综合工具对文件粒度有要求，一个文件多个模块可能报错
- 团队协作：两个人不会同时改同一个文件，减少冲突
核心原则：文件名 = 模块名。比如模块叫 uart_top，文件就叫 uart_top.v。别搞什么 top_module.v 里面放 uart_top，这种命名不一致的坑，我踩过不止一次。
二、文件头注释模板
文件头注释，很多人觉得是形式主义。但我想说：三个月后的你，会感谢现在写注释的自己。
我曾经接手过一个项目，文件头干干净净，连个日期都没有。我花了整整一周去猜：这个模块是谁写的？什么时候写的？版本是哪个？后来我养成了一个习惯——每个文件开头必须有一个标准注释块。
我个人习惯的模板是这样的：
// *****************************************************************************
// 模块名 : uart_top
// 文件名 : uart_top.v
// 作者 : Zhang San
// 日期 : 2024-01-15
// 版本 : v1.0
// 描述 : UART顶层模块，集成发送和接收子模块
// 修改记录 :
// v1.0 - 初始版本
// v1.1 - 修复波特率计算溢出问题 (2024-02-01)
// *****************************************************************************这里有几个要点：
- 模块名和文件名必须一致——这是硬性要求
- 修改记录要写清楚改了啥——别只写「修复bug」，要写「修复波特率计算溢出问题」
- 日期格式统一——我建议用 YYYY-MM-DD，别用 01/15/2024 这种容易混淆的格式
小技巧：可以在文件头里加一行「依赖关系」，比如「依赖：clk_div.v, uart_rx.v」。这样别人一看就知道需要哪些文件。
三、模块声明格式
模块声明，就是 module ... endmodule 那一段。格式规范了，代码可读性直接提升一个档次。
我见过最离谱的写法：
module uart_top(clk,rst_n,tx,rx,data_in,data_out,valid);所有端口挤在一行，连个换行都没有。你想想看，如果这个模块有 50 个端口，这行代码得有多长？
我建议的格式是这样的：
module uart_top (
// 系统接口
input wire clk, // 系统时钟，50MHz
input wire rst_n, // 异步复位，低有效
// UART 接口
output wire tx, // UART 发送
input wire rx, // UART 接收
// 数据接口
input wire [7:0] data_in, // 待发送数据
output wire [7:0] data_out, // 接收到的数据
output wire valid // 数据有效标志
);看到了吗？几个关键点：
- 每个端口单独一行——别挤在一起
- 按功能分组——系统接口、UART接口、数据接口，分组清晰
- 注释写清楚——时钟频率、有效电平、数据位宽，这些信息对使用者很重要
- 逗号在行尾——这样增删端口时，只需要改一行，不会影响其他行
注意：有些工具（比如某些老版本的 VCS）对注释中的特殊字符敏感。建议注释里不要用中文标点，统一用英文标点。这个坑我踩过——因为注释里写了个中文分号，结果编译报错，查了半天才发现。
四、端口列表排列顺序
端口顺序，看似小事，实则影响巨大。我见过一个项目，端口顺序完全随机——输入输出混在一起，时钟和复位插在数据中间。每次看代码都要从头到尾扫一遍，才能找到想要的端口。
我建议的排列顺序：
| 优先级 | 端口类型 | 示例 |
|---|---|---|
| 1 | 时钟和复位 | clk, rst_n |
| 2 | 控制信号（输入） | en, start, mode_sel |
| 3 | 数据信号（输入） | data_in, addr_in |
| 4 | 控制信号（输出） | done, busy, error |
| 5 | 数据信号（输出） | data_out, addr_out |
| 6 | 双向信号 | sda, scl |
为什么要这么排？
- 时钟复位放最前面——这是模块的「心脏」，一眼就能看到
- 输入在前，输出在后——符合数据流向，从左到右
- 控制信号在前，数据信号在后——先看控制逻辑，再看数据通路
- 双向信号放最后——因为双向信号处理特殊，容易出问题，放在最后提醒自己注意
避坑指南：我曾经在一个项目中，把双向信号 sda 放在了时钟后面。结果综合工具报错，说双向信号不能和时钟放在一起。后来查手册才知道，有些工具对端口顺序有隐含要求。所以，双向信号放最后，这是血的教训。
五、知识体系总览
下面这张图，把本章的核心逻辑串起来了。你可以把它当作一个检查清单——写代码前看一眼，确保没漏掉什么。
嗯，以上就是第四章的全部内容。文件与模块结构规范，说白了就是「让别人能看懂你的代码」。你想想看，如果每个文件都整整齐齐，端口排列井井有条，接手你代码的人得多感激你？
记住：规范的代码，是对未来同事的尊重。
最后一个小建议：可以在项目根目录放一个 CODING_STYLE.md 文件，把本章的规范写进去。新同事来了，先看这个文件，能省很多沟通成本。我之前的团队就是这么做的，效果很好。
可可精品资料库