命名规范（上）：模块名、端口名、信号名、参数名的命名规则与最佳实践
各位同学好，我是你们的讲师。今天咱们聊聊命名规范。
说实话，我见过太多因为命名混乱导致的调试噩梦。一个项目几百个文件，信号名乱七八糟，连原作者自己都看不懂。嗯，这其实是个态度问题。命名规范，说白了就是代码的「门面」。
一、模块名：项目的身份证
模块名，就是你这个模块的身份证。我个人习惯用 小写字母 + 下划线 的组合。比如 uart_top、spi_master、i2c_slave。为什么不用大写？因为 Verilog 本身不区分大小写，但为了可读性，我们约定俗成用小写。
核心原则：模块名要能反映功能，不要用 top、module1 这种毫无信息量的名字。
我在项目中遇到过一件事：有个同事把模块命名为 test，结果后来项目里出现了三个 test 模块，编译直接报错。你想想看，这种低级错误完全可以避免。
命名规则总结如下：
| 场景 | 推荐格式 | 示例 |
|---|---|---|
| 顶层模块 | 项目名_top | soc_top |
| 功能模块 | 功能名_类型 | fifo_wrapper |
| 接口模块 | 协议名_interface | axi_interface |
| 测试模块 | 模块名_tb | uart_tb |
二、端口名：模块的对外接口
端口名，就是模块和外界沟通的桥梁。我建议端口名也用小写字母 + 下划线。但有个例外——时钟和复位。我个人习惯用 clk 和 rst_n，其中 _n 表示低电平有效。
为什么强调这个？因为有一次我接手一个项目，复位信号叫 reset，没有后缀。结果仿真时发现复位逻辑反了，查了半天才发现是极性搞错了。从那以后，我要求团队所有复位信号必须加 _n 或 _p 后缀。
小技巧：端口方向用 input、output、inout 明确标注，不要省略。我见过有人写 wire [7:0] data 当端口用，结果综合时报错。
端口命名的最佳实践：
- 时钟：clk、clk_50m、clk_core
- 复位：rst_n、rst_async_n
- 数据：data_in、data_out、addr
- 控制：en、sel、we、re
三、信号名：模块内部的脉络
信号名是模块内部的「血管」，命名好坏直接影响代码可读性。我见过最夸张的命名是 a、b、c……这种代码，别说别人看不懂，过两周你自己都忘了。
我个人习惯用 名词 + 动词 的组合。比如 data_valid、fifo_full、tx_done。这样一看就知道信号是干什么的。
注意：不要用缩写！除非是业界通用缩写（比如 fifo、uart、spi）。我曾经见过有人用 d_vld 表示 data_valid，结果团队里三个人有三种理解。嗯，这其实是在给自己挖坑。
信号命名规则：
| 类型 | 命名规则 | 示例 |
|---|---|---|
| 数据信号 | 数据名_属性 | data_valid、data_ready |
| 控制信号 | 功能_动作 | write_enable、read_start |
| 状态信号 | 状态名_st | idle_st、busy_st |
| 计数器 | cnt_用途 | cnt_tx、cnt_rx |
四、参数名：代码的「可调旋钮」
参数名，说白了就是代码里的「可调旋钮」。我建议用 大写字母 + 下划线。比如 DATA_WIDTH、FIFO_DEPTH、CLK_FREQ。这样一眼就能看出是参数，不是信号。
为什么用大写？因为 Verilog 中参数是编译时常量，用大写可以跟普通信号区分开。我在项目中遇到过有人把参数写成小写，结果跟信号混在一起，改参数时改错了地方，仿真跑了两天才发现。
最佳实践：参数名要包含单位或含义。比如 CLK_FREQ_50M 比 FREQ 好得多。我习惯在参数名里加上默认值，比如 DATA_WIDTH = 8，这样别人一看就知道默认是多少。
参数命名示例：
// 好的命名
parameter DATA_WIDTH = 8;
parameter FIFO_DEPTH = 256;
parameter CLK_FREQ_MHZ = 50;
// 差的命名
parameter w = 8; // 谁知道 w 是什么？
parameter dep = 256; // dep 是 depth 还是 depend？
五、知识体系框架
下面这张图，是我自己总结的命名规范知识体系。你想想看，命名规范其实就四个维度：模块名、端口名、信号名、参数名。每个维度都有对应的规则和最佳实践。
六、避坑指南
最后，分享几个我踩过的坑：
- 不要用关键字做名字：比如
module、wire、reg。我曾经见过有人把信号命名为wire，结果编译报错，查了半天才发现是关键字冲突。 - 不要用数字开头：比如
1st_data、2nd_flag。Verilog 不允许数字开头，但有些人就是记不住。 - 不要用连续下划线：比如
data__valid。这种命名容易让人误以为是两个下划线，其实只是一个。 - 不要用大小写混搭：比如
DataValid。虽然 Verilog 不区分大小写，但混搭风格会让代码看起来很乱。
我的建议：团队内部统一一份命名规范文档，每个人写代码前先看一遍。我带的团队，新人入职第一件事就是背命名规范。嗯，这听起来有点苛刻，但效果真的很好。
好了，命名规范的上半部分就讲到这里。记住，好的命名习惯，能让你少加一半的班。下次咱们聊命名规范的下半部分——文件命名、层次化命名和总线命名。