2、命名规范（上）：模块名、端口名、信号名的命名规则，避免使用歧义缩写

好，咱们正式开始聊命名规范。

说实话，我见过太多因为命名不规范而翻车的项目了。有一次我接手一个别人留下的模块，里面有个信号叫 tmp_out，我琢磨了半天——这到底是「临时输出」还是「温度输出」？后来查代码上下文才发现，它其实是「三态输出」的缩写。你说坑不坑？

所以这一章，咱们就把模块名、端口名、信号名的规矩说清楚。说白了，命名这件事，就是给别人看的，也是给未来的自己看的。

2.1 模块名：一眼看出它是什么

模块名，我建议用「功能+类型」的结构。比如 uart_tx、spi_master、fifo_async。这样别人一看就知道：哦，这是个UART发送模块，这是个SPI主设备，这是个异步FIFO。

我个人习惯用下划线分隔单词，全部小写。比如 i2c_slave 而不是 I2CSlave 或 i2cSlave。为什么？因为Verilog和SystemVerilog对大小写敏感，全部小写可以避免一些低级错误。

嗯，这里要注意：模块名不要超过20个字符。太长了，综合工具和仿真工具都会觉得烦，你自己写代码也容易打错。

推荐	不推荐	说明
uart_rx	urx	urx是什么？没人知道
spi_master	spi_m	m是master还是memory？歧义
fifo_async	fifo_a	a是async还是address？

2.2 端口名：输入输出要清晰

端口命名，我有个铁律：方向前缀 + 功能名。

比如输入端口用 i_ 开头，输出端口用 o_ 开头，双向端口用 io_ 开头。这样你在看代码的时候，一眼就能分清信号方向。

举个例子：

module uart_tx (
    input  logic       i_clk,      // 时钟
    input  logic       i_rst_n,    // 复位，低有效
    input  logic       i_data_en,  // 数据使能
    input  logic [7:0] i_data,     // 待发送数据
    output logic       o_tx,       // 串行输出
    output logic       o_busy      // 忙标志
);

你看，每个端口的功能一目了然。我曾经见过一个项目，端口名全是 a、b、c 这种，结果调试的时候根本分不清哪个是哪个，最后只能对着原理图一个一个对——那叫一个痛苦。

2.3 信号名：别用歧义缩写

信号命名，是重灾区。我见过最离谱的是 cnt——它到底是 counter 还是 control？还有 reg，在Verilog里是关键字，你拿它当信号名，综合直接报错。

我总结了几条经验：

• 缩写要有共识：比如 clk（时钟）、rst（复位）、en（使能）、addr（地址）、data（数据）。这些是行业通用缩写，没问题。
• 避免自创缩写：比如 tmr（是timer还是temp？）、cfg（是config还是cough？）。
• 长度适中：信号名建议8-20个字符。太短容易歧义，太长写起来累。

举个例子，假设你要表示「写地址有效」这个信号：

推荐	不推荐	原因
wr_addr_valid	wav	wav是波形文件？还是写地址有效？
wr_addr_vld	wavld	读起来像外星语
write_addr_valid	w_addr_v	v是valid还是vector？

2.4 避坑指南：我曾经踩过的坑

我曾经接手过一个模块，里面有个信号叫 rst_n。你猜怎么着？它居然是高有效复位！因为设计者觉得 _n 后缀只是装饰。结果我仿真跑了一整天，发现复位逻辑全反了。从那以后，我规定团队里：_n 后缀必须表示低有效，_p 后缀表示高有效，谁都不许乱用。

还有一次，我看到一个信号叫 data_rdy，心想这是 data ready 吧？结果代码里写的是 data_rdy = data_in & rdy_signal——它居然是 data AND rdy！你说这命名坑不坑？

2.5 知识体系图

下面这张图，帮你理清命名规范的核心逻辑：

2.6 总结一下

命名规范这件事，说白了就是「约定大于配置」。你一个人写得爽，团队其他人看不懂，那这代码就是废的。

我个人习惯在项目开始前，先花10分钟把命名规范文档写出来，大家签字确认。这样后面谁写错了，直接拿文档怼回去——省心。

好了，这一章就到这里。记住：好的命名，是代码最好的注释。

可可精品资料库