Un buen estilo de codificación facilita la lectura, depuración y modificación del código. Aunque el código Verilog puede escribirse de cualquier manera siempre que la sintaxis sea correcta, un estilo de codificación descuidado suele ser un trabajo de una sola vez. A veces, al revisar el código que uno mismo ha escrito, no se distingue el significado de las señales ni se comprende la función del módulo, y hay que analizarlo paso a paso desde la lógica, lo que consume gran cantidad de tiempo y esfuerzo para asimilarlo, afectando seriamente el progreso del diseño.

Para evitar que otros o uno mismo exclamen sinceramente: ¡¿Qué "pequeño bobo" escribió este código?! A continuación se ofrecen algunas sugerencias sobre el estilo de codificación.

Sobre la nomenclatura

Las variables de señal, los módulos, etc. deben usar nombres con significado, y los nombres de las señales deben mantenerse sin cambios cuando viajan entre módulos, para que el código tenga información descriptiva clara y mejore la legibilidad.

Cuando un nombre tenga demasiadas palabras, se pueden concatenar usando mayúscula inicial o un guion bajo "_". Personalmente prefiero la segunda opción, es más clara.

  reg     DataToDestinationClock ;
  reg     data_to_destination_clock ; //Recomendado

Se recomienda usar abreviaturas de palabras para nombrar las señales, y saber elegirlas, para evitar nombres de señales demasiado largos. Por ejemplo, clock se abrevia como clk, destination como dest, source como src, etc.

reg data_to_destination_clock ; reg des_data ; //Recomendado

Use ingeniosamente números para representar letras inglesas, por ejemplo, 2 representa "to", 4 representa "for", se puede ahorrar un poco de espacio de código.

  reg     clk_for_test, sig_uart_to_spi ;
  reg     clk4test, sig_uart2spi ; //推荐

Aunque Verilog distingue entre mayúsculas y minúsculas, se recomienda que los nombres de los módulos funcionales, puertos, variables de señal, etc. usen minúsculas; los parámetros (parameter) usen mayúsculas; y algunos puertos especiales como los de alimentación, pad, etc. usen mayúsculas. Esto es solo por conveniencia al escribir código, para distinguir fácilmente constantes y variables, sin preocuparse por la diferencia entre variables de señal con el mismo nombre pero diferente capitalización.

  parameter         DW = 8 ; //常量
  reg [DW-1 : 0]    wdata ;  //变量

Las variables de registro generalmente se les añade un sufijo_r, las variables con retardo de ciclos se les añade un sufijo_r1、_r2etc. Esto tiene dos grandes ventajas. Primero, durante el diseño RTL es fácil operar con los datos según el tipo de variable. Segundo, los nombres de las señales en la netlist sintetizada suelen cambiar; añadir sufijos facilita encontrar en la netlist sintetizada las variables de señal correspondientes en el RTL.

  wire      dout_en ;
  reg       dout_en_r ;
  ...  //dout_en_r 的逻辑
  assign    dout_en = dout_en_r ;

Otros sufijos:_dpueden indicar señales después del retardo,_tpueden indicar señales almacenadas temporalmente,_npueden indicar señales activas en bajo (low active),_spueden indicar señales de slave,_mpueden indicar señales de master, etc.

Evite usar palabras reservadas (keywords) para nombrar señales, por ejemploin, out, x, zno se recomiendan como variables.

El nombre del archivo debe mantenerse consistente con elmodulenombre del diseño; dentro del archivo, en lo posible, incluya solo un módulo de diseño.

Sobre los comentarios

Al inicio de cada módulo de diseño se debe incluir información de descripción del archivo, como derechos de autor, nombre del módulo, autor, fecha, resumen, historial de modificaciones, etc. Por ejemplo:

/**********************************************************
// Copyright 1891.06.02-2017.07.14
// Contact with willrious@sina.com
================ ejemplo.v ======================
>> Author       : willrious
>> Date         : 1995.09.07
>> Description  : Welcome
>> note         : (1)To 
>>              : (2)My
>> V180121      : World.
************************************************************/

Los comentarios deben expresar de manera concisa el significado que describe el código. Los comentarios cortos se añaden después de la línea de código; los comentarios largos se escriben en una línea aparte antes del código.

   //输出位宽小于输入位宽,求取缩小的倍数及对应的位数
   parameter       SHRINK       = DWI/DWO ;
   reg [AWI-1:0]         ADDR_WR ; //写地址

Escriba los comentarios preferiblemente en inglés, para garantizar que se muestren correctamente en diferentes sistemas operativos y editores.

En las señales de puerto, además de las señales habituales de reloj y reset, es mejor comentar también el resto de señales.

La función de los comentarios es muy potente; se puede usar información en comentarios para dibujar diagramas de temporización, e incluso para dibujar diagramas de circuitos digitales.

Sobre la optimización

Use paréntesis para determinar la prioridad o la estructura lógica del programa. Para evitar errores de diseño por problemas de precedencia de operadores, se recomienda usar paréntesis con frecuencia. Al mismo tiempo, el uso inteligente de paréntesis a veces también optimiza la estructura tras la síntesis lógica. Por ejemplo:

    //A menudo se sintetiza como 3 sumadores en serie
    assign F = A + B + C + D ;
    //A menudo se sintetiza como 2 sumadores en paralelo y 1 sumador en cascada, con una temporización más holgada
    assign F = (A + B) + (C + D) ;
 
    //No recomendado
    assign flag = cnt == 4'd2 && mode == 2'b01;
    //Recomendado
    assign flag = (cnt == 4'd2) && (mode == 2'b01);  

Para las sentencias condicionales, use preferentemente la sentencia case en lugar de if. Cuando hay demasiadas sentencias de condición al mismo nivel, la estructura de hardware sintetizada con case suele consumir menos recursos y tener mejor temporización que con if.

Al escribir máquinas de estado, use preferentemente el estilo de 3 procesos (three-process), para garantizar que el código sea limpio y seguro.

En el diseño de sistemas, use preferentemente el método de dividir los módulos según su función y luego instanciarlos. En comparación con integrar miles de líneas de código en un solo archivo, la división de módulos favorece el trabajo en equipo y facilita las actualizaciones y el mantenimiento.

Sobre la estética

Para las señales de puerto, asegúrese de colocar una señal por línea, con la coma justo después de la declaración del puerto. Si tiene un trastorno obsesivo-compulsivo, mantenga también las comas alineadas.

//No recomendado
module even_divisor (input rstn, clk, output clk_div2, clk_div4, clk_div10) ;

//Recomendado
module even_divisor    (
    input               rstn     ,
    input               clk      ,
    output              clk_div2 ,
    output              clk_div4 ,
    output              clk_div10
    );

Cuando una línea de código sea demasiado larga, es preferible escribir en varias líneas, sin necesidad de usar caracteres de continuación. Por ejemplo:

      assign rempty    = (rover_flag == rq2_wptr_decode[AWI]) &&
                         (raddr_ex >= rq2_wptr_decode[AWI-1:0]);

Use preferentemente la estructura begin + end para garantizar la relación de anidamiento entre las sentencias. begin va en la misma línea que la palabra clave, y end en una línea aparte. Por ejemplo, al usar bloques always, o cuando una sentencia condicional tiene solo una sentencia de ejecución, se pueden omitir las palabras clave begin + end. Pero para garantizar la integridad de la estructura y la posterior depuración y modificación del código, se recomienda añadir estas palabras clave.

   always @(posedge dout_clk or negedge rstn) begin
      if (!rstn) begin
         dout_en_r       <= 1'b0 ;
      end
      else begin
         dout_en_r       <= rd_en_wir ;
      end
   end

Use preferentemente la tecla Tab y espacios para alinear las sentencias según la jerarquía. También debe dejar espacios entre variables, palabras clave y operadores para facilitar el análisis lógico.

   generate
      if (DWO >= DWI) begin
         reg [DWI-1:0]         mem [(1<<AWI)-1 : 0] ;
         always @(posedge CLK_WR) begin
            if (WR_EN) begin
               mem[ADDR_WR]  <= D ;
            end
         end
      end
   endgenerate

Al instanciar módulos, separe las señales de puerto de las señales de conexión y alinéelas por separado. Cuando la señal de conexión sea un vector, indique su ancho de bits para facilitar la lectura y depuración.

    ram   u_ram(
        .CLK_WR          (clk),
        .WR_EN           (wren), //No escribir cuando esté lleno
        .ADDR_WR         (addr),
        .D               (wdata[9:0]),
        .Q               (rdata[31:0])
        );

Al instanciar varios módulos idénticos, use preferentemente la sentencia generate para evitar una descripción de instanciación demasiado larga.