Verilog应用浅见之一——关于代码风格

    我应该算是一个硬件工程师，涉及比较底层的技术。从原理图上放电阻，到设计PCB和写PCB设计任务书，到焊接调试电路板，再到写设备驱动，写FPGA程序，写各类文档，写项目申请书，所有的事情都干过。使用Verilog也有一些年头了，虽然只占整个工作的一部分，但是相对于其他事情，写Verilog程序、仿真和在FPGA中跑起来应该是我更喜欢做的事情。在这个过程中也积累了不少经验，有了一些个人的见解。

    工作挺累的，但还是想把这些东西写出来，与大家分享，也有机会听听大家的意见。

    本来想先从Verilog语法开始写，不过这类资料、文章、讨论、帖子恐怕比我敲过的代码还要多。所以还是以个人的经验和见解为主吧，以后这一系列的文章也是这样。既然以个人经验和见解为主，就不涉及“道路”之争，对错之争，只是把他们抛出来，让大家有所借鉴，或加以指点。所以还是回到本文的主题——代码风格。

    代码风格的主要要素有：命名、括号的使用、疏密的控制、缩进、注释。代码风格首先为可读性服务，其次还是为可读性服务。至于美观，我想看着美的程序，大多数可读性都不差。

    1. 命名

    在程序中，凡是用户自己定义、设计、例化的东西都需要命名，比如变量、module、task、function等等。说起命名这件事儿，第一条不能违背的规则就是：不要使用拼音，不要使用拼音！！！

    这倒不是咱觉得英文高大上，而是语言之间存在的天然的区别。到目前为止，世界上几乎所有被广泛使用的和被在一定范围内使用的编程语言都是基于英文的。这是历史原因决定的，这是工业革命、电子技术革命、信息革命发生在英语国家决定的。这些编程语言都只接受字母作为输入，不接受汉字。中文是象形文字的巅峰，但是在表音方面并不擅长，当命名数多以后会非常混乱。如果哪天有一种编程语言是基于中文的，那时候用汉字来命名变量将是一件非常惬意的事情。

    每个人都有自己的命名偏好，以下是我自己在Verilog程序中遵循的规则和建议。

    1.1 不要使用拼音，不要使用拼音！！！

    我不只一次见到过使用拼音定义变量和module的源程序，为了探究shuzhi、jieguo、chengji、wendu、shidu、du、mi......到底是什么意思，花了很多时间在翻看上下文、查询电话号码、打电话和等待上面。中文并不是擅长表音的文字，所以shuzhi到底是“数值”还是“树脂”，抑或是“竖直”？chengji到底是“成绩”还是“乘积”？如果遇到个普通话不标准的，打错了zh、ch、sh、s的，或者干脆上方言的，为此而消耗的精力都够写封辞职信然后再找份工作了。

    一个复杂点的设计，如果一个月不碰，再看自己的代码都不一定很快看懂。何况使用这种命名方法的程序呢？

    1.2 使用合理的命名规则

    至少在一个项目中要使用相同的命名规则。我一般采用的命名规则如下。

    1.2.1 变量

    对于变量，我始终使用小写英文单词、数字和下划线的组合。涵义简单的变量就直接使用单词或单词的简写表示，涵义比较复杂的，会使用单词或单词简写+下划线的方式。比如在我曾经的项目中，设备中有驱动单元和比较单元，驱动单元负责产生时序和格式复杂的向量，比较单元负责按照一套预下载的动态规则对采样数据进行处理。我人为，绝大部分命名和缩写行为都是和项目的实际情况相关的，不能完全孤立的讨论这个问题。在该项目中，我的很多变量名如下。

    drv_strength、cmp_thresh、cur_cmp_sts、rdy4rd、rdy4wr、pat_start、event_pos、hmc7044_wr、hmc7044_sdo......

    围绕命名，我们将从下面几个角度来讨论。

    （1）通用的单词简化

    通用的单词简化我会在绝大部分项目中使用，即使和我其他的一些缩写产生冲突，也会维持通用缩写不变。比如下表这些常用的缩写。

 

完整的单词	缩写后的单词
reset	rst
asynchronous	async
status	sts
valid	vld
write	wr
read