良好的代码编写风格（二十五条）(转贴)

edit

良好代码编写风格可以满足信、达、雅的要求。在满足功能和性能目标的前
提下，增强代码的可读性、可移植性，首要的工作是在项目开发之前为整个设计
团队建立一个命名约定和缩略语清单，以文档的形式记录下来，并要求每位设计
人员在代码编写过程中都要严格遵守。
良好代码编写风格的通则概括如下：
（1） 对所有的信号名、变量名和端口名都用小写，这样做是为了和业界的习惯
保持一致；对常量名和用户定义的类型用大写；
（2） 使用有意义的信号名、端口名、函数名和参数名；
（3） 信号名长度不要太长；
（4） 对于时钟信号使用clk 作为信号名，如果设计中存在多个时钟，使用clk
作为时钟信号的前缀；
（5） 对来自同一驱动源的信号在不同的子模块中采用相同的名字，这要求在芯
片总体设计时就定义好顶层子模块间连线的名字，端口和连接端口的信号
尽可能采用相同的名字；
（6） 对于低电平有效的信号，应该以一个下划线跟一个小写字母b 或n 表示。
注意在同一个设计中要使用同一个小写字母表示低电平有效；
（7） 对于复位信号使用rst 作为信号名，如果复位信号是低电平有效，建议使
用rst_n；
（8） 当描述多比特总线时，使用一致的定义顺序，对于verilog 建议采用
bus_signal[x:0]的表示；
（9） 尽量遵循业界已经习惯的一些约定。如*_r 表示寄存器输出，*_a 表示异
步信号，*_pn 表示多周期路径第n 个周期使用的信号，*_nxt 表示锁存前
的信号，*_z 表示三态信号等；
（10）在源文件、批处理文件的开始应该包含一个文件头、文件头一般包含的内
容如下例所示：文件名，作者，模块的实现功能概述和关键特性描述，文
件创建和修改的记录，包括修改时间，修改的内容等；
（11）使用适当的注释来解释所有的always 进程、函数、端口定义、信号含义、
变量含义或信号组、变量组的意义等。注释应该放在它所注释的代码附近，
要求简明扼要，只要足够说明设计意图即可，避免过于复杂；
（12）每一行语句独立成行。尽管VHDL 和Verilog 都允许一行可以写多个语句，
当时每个语句独立成行可以增加可读性和可维护性。同时保持每行小于或
等于72 个字符，这样做都是为了提高代码得可读性；
（13）建议采用缩进提高续行和嵌套语句得可读性。缩进一般采用两个空格，如
西安交通大学SOC 设计中心
2
果空格太多则在深层嵌套时限制行长。同时缩进避免使用TAB 键，这样
可以避免不同机器TAB 键得设置不同限制代码得可移植能力；
（14）在RTL 源码的设计中任何元素包括端口、信号、变量、函数、任务、模
块等的命名都不能取Verilog 和VHDL 语言的关键字；
（15）在进行模块的端口申明时，每行只申明一个端口，并建议采用以下顺序：
输入信号的clk、rst、enables other control signals、data and address signals。
然后再申明输出信号的clk、rst、enalbes other control signals、data signals；
（16）在例化模块时，使用名字相关的显式映射而不要采用位置相关的映射，这
样可以提高代码的可读性和方便debug 连线错误；
（17）如果同一段代码需要重复多次，尽可能使用函数，如果有可能，可以将函
数通用化，以使得它可以复用。注意，内部函数的定义一般要添加注释，
这样可以提高代码的可读性；
（18）尽可能使用循环语句和寄存器组来提高源代码的可读性，这样可以有效地
减少代码行数；
（19）对一些重要的always 语句块定义一个有意义的标号，这样有助于调试。
注意标号名不要与信号名、变量名重复；
（20）代码编写时的数据类型只使用IEEE 定义的标准类型，在VHDL 语言中，
设计者可以定义新的类型和子类型，但是所有这些都必须基于IEEE 的标
准；
（21）在设计中不要直接使用数字，作为例外，可以使用0 和1。建议采用参数
定义代替直接的数字。同时，在定义常量时，如果一个常量依赖于另一个
常量，建议在定义该常量时用表达式表示出这种关系；
（22）不要在源代码中使用嵌入式的dc_shell 综合命令。这是因为其他的综合工
具并不认得这些隐含命令，从而导致错误的或较差的综合结果。即使使用
Design Compiler，当综合策略改变时，嵌入式的综合命令也不如放到批处
理综合文件中易于维护。这个规则有一个例外的综合命令，即编译开关的
打开和关闭可以嵌入到代码中；
（23）在设计中避免实例化具体的门级电路。门级电路可读性差，且难于理解和
维护，如果使用特定工艺的门电路，设计将变得不可移植。如果必须实例
化门电路，我们建议采用独立于工艺库的门电路，如SYNOPSYS 公司提
供的GTECH 库包含了高质量的常用的门级电路；
（24）避免冗长的逻辑和子表达式；
（25）避免采用内部三态电路，建议用多路选择电路代替内部三态电路。