9.1 编码规范与 Lint：让机器替你守夜

9.1 编码规范与 Lint：让机器替你守夜

本节摘要：编码规范防的是「人写出机器误读的代码」，Lint 工具把规范变成机器可执行的检查。命名、结构、复位三大类规范各有明确的防线对象；Lint 接进日常流程后，大多数低级错误活不过保存键。规范不是美学洁癖，是便宜的防线投资。

错案侦破之前，先讲防案的手段。这一节审两样最便宜也最有效的防线：编码规范（人遵守的条款）与 Lint（机器执行的检查）。两者的关系是「规范写给人看，Lint 替人守」——好的规范最终都会沉淀成 Lint 规则，让守夜不需要熬夜。

命名规范：防线从名字开始

命名的防线价值在「望文生义的正确性」。行业通行的命名约定长这样：

module uart_rx #(                     // 模块名：小写下划线，见名知义
    parameter CLKS_PER_BIT = 104      // 参数：全大写
)(
    input  wire        clk,           // 时钟一律叫 clk 或带域后缀
    input  wire        rst_n,         // 复位带有效电平后缀：低有效加 _n
    input  wire        rx_in,
    output wire [7:0]  data_out,
    output wire        done_tick      // 单拍脉冲加 _tick 或 _pulse 后缀
);
    wire        rx_sync;               // 同步器输出加 _sync
    reg   [7:0] shifter;               // 中间寄存器描述用途
endmodule
​

几条后缀约定值得标准化：_n 标低有效、_sync 标同步器输出、_r 或 _q 标寄存器输出、_tick 标单拍脉冲、_async 标未同步信号。这些后缀本身就在传递时序信息——评审时看到 _async 信号连进纯组合逻辑，不用懂功能就能提出跨域质疑。命名规范的检验标准很朴素：新成员不看实现，仅凭端口表能猜对模块的行为与敏感信号，这份命名就合格。

结构规范：防的是「机器误读」

结构类规范防的是语义模糊的写法——代码能跑，但人和工具都可能读歪：

// 规范条款逐条对照（注释即条款）
// 条款一：一个 always 块只干一件事，组合时序不混
// 条款二：时序块用非阻塞、组合块用阻塞，块内禁混
// 条款三：组合块只用通配敏感，边沿块手写时钟与异步复位
// 条款四：状态机三段式，次态变量只在次态块赋值
// 条款五：位宽显式，字面量带位宽，不靠上下文猜
// 条款六：复位条款写明策略，异步复位同步释放

always @(posedge clk) begin          // 时序块样板头
    if (!rst_n) begin
        shifter <= 8'd0;             // 字面量带位宽
    end else if (rx_sync) begin
        shifter <= {shifter[6:0], rx_in};   // 非阻塞
    end
end
​

这六条在前面的章节全部论证过机理，这里收拢成条款。条款化有个额外收益：它们几乎都能转成 Lint 规则，机器逐条检查——「非阻塞块内混用阻塞赋值」「组合块手写敏感列表」「字面量缺位宽」都是 Lint 的标配检查项。规范与规则的对应关系，让「规范执行率」从主观印象变成客观数字。

复位规范：单独一档的严查项

复位值得单独一档，因为它的错误距离症状太远。复位规范的核心条款：哪些寄存器必须复位（控制状态必须、数据流水可豁免）、复位值必须有明确依据、异步复位必须过同步器（4.3 节的复位同步器）、复位释放的时序必须纳入分析。评审复位条款的提问模板固定：这个寄存器上电后的值从哪来？复位覆盖不到它时，第一拍它会输出什么？这两个问题能逼出大半复位设计的漏洞。

Lint 的工程接入

Lint 工具的接入分三步走，成本从低到高。第一步，编辑器内嵌：用 Verilator 的纯检查模式或各开发环境的插件，保存即查，错误反馈以秒计——这一步几乎零成本，收益却覆盖日常编码的全部低级错误。第二步，入库门禁：提交钩子里跑全库 Lint，新增告警一律拦下，存量告警限期清零——「告警只减不增」是关键政策，放任告警堆积等于关掉防线。第三步，夜间全量与趋势：每夜对整个代码库跑深度检查，输出告警趋势曲线，配合规则升级。

工具的选择前面 8.4 节给过地图，这里补使用建议：商业 Lint 的规则库深、误报率经过调校，大项目首选；Verilator 的检查模式覆盖高频项、速度极快，个人与中小项目的性价比之选。无论哪个工具，都有同一份使用纪律：每条告警要么修复、要么豁免并注明理由，不存在第三种处置——「看过但没动」的告警会迅速淹没有效信号。

案例展开：一次告警清零运动的账本。 背景：某团队接手一个有年代的项目，Lint 全库告警四位数，团队对告警早已麻木。操作：分档处理——锁存器、多驱动、组合环三类高危告警全部修复（配合回归验证）；位宽类告警逐条核对，真问题修复、设计意图如此的全部显式豁免加注释；风格类告警批量格式化处理。结果：全库告警降到个位数并进入门禁管控，此后两个季度新引入的高危缺陷数量明显下降，其中两起潜在锁存器问题在编辑器内就被拦下。解读：告警的价值取决于处置纪律——麻木状态下四位数告警的防线价值为零，清零之后个位数告警条条刺眼。防线投资的意义不在工具本身，而在「让信号重新可读」。变式：存量告警太多时按「高危清零、中危豁免登记、低危随改随清」的节奏分批，避免一次性整改引入新风险——大爆炸式整改本身就是风险源。

规范的落地形态

最后交代规范的落地。书面规范没人看是常态，有效的形态是三层：一份一页纸的速查卡（高频条款加正反例）、一套 Lint 规则（机器执行）、一个评审提问模板（人工补位）。三层覆盖后，规范的执行不再依赖自觉。还有一条务实建议：规范条款都要能回答「这条防的是什么病」，答不出来的条款删掉——规范的数量与权威性成反比，条条有案的十条，胜过面目模糊的一百条。

本节要点回顾

• 命名传递时序信息：低有效、同步、单拍脉冲的后缀约定，让评审不看实现就能提问；
• 结构条款都可机检：六条结构规范几乎全是 Lint 标配项，规范执行率因此可量化；
• 复位单独严查：上电值从哪来、覆盖不到时输出什么，两问逼出漏洞；
• Lint 三步接入：编辑器即查、入库门禁、夜间趋势，拦截越早越便宜；
• 告警处置二选一：修复或豁免注明理由，「看过没动」会淹没有效信号；
• 规范贵在条条有案：防什么病说不清的条款就删，十条有案的强过一百条糊涂的。

防线布好后，接下来练刑侦技术：竞争、毛刺、亚稳态三大疑案的侦破手法。