Actualmente me encuentro desarrollando mi trabajo de grado (tesis) en ingeniería electrónica y uno de los primeros tópicos que acordé con mi compañero, era definir algunas pautas básicas para la escritura y estructuración del código que íbamos a tener que desarrollar, incluso sin saber aún muy bien la complejidad de las arquitecturas que vamos a tener que describir, pero esto no necesariamente es un impedimento para plantear algunas reglas generales.

Las guías de estilo, son un conjunto de reglas normalmente acordadas entre los desarrolladores que puede ser extenso o solo contener algunas pocas reglas, pero que al final van a terminar contribuyendo a la legibilidad y comprensión mucho más rápida para otros profesionales que posiblemente en el futuro lleguen a hacer mantenimiento del sistema o simplemente a comprender algunas partes del mismo.

Acordamos una guía relativamente sencilla y que quiero compartir con todos, tomamos algunas observaciones de algunos proyectos de software libre reconocidos como el proyecto Code::Blocks, entre otros y los trajimos a Verilog sin caer en la complejidad (para complejidad ya está el proyecto) pero que ayudaran a mantener una coherencia en la escritura general de las micro-arquitecturas y la arquitectura final.


¡Muéstrame la Guía!

Hasta ahí dejo la introducción, a continuación una descripción muy breve de lo acordado y algunos ejemplos gráficos para que sea más “recordable“.

  • Estructura de los Delimitadores begin – end.

Aunque según el lenguaje no es absolutamente necesario, hemos decidido iniciar los bloques con la palabra begin en la misma línea que la palabra reservada que corresponda (ej. if, always, etc)

HDL guia 1

  • Declaración de Puertos Entrada – Salida.

Normalmente cuando describimos arquitecturas en general estas tienen entradas y salidas, lo que en esta guía hemos llamado “puertos” y que solo declaramos sus nombres en la declaración misma del módulo, pero no su dirección (input, output, inout).

  • Declaración de Parámetros (parameters).

Se ha decidido realizar la declaración de parámetros dos líneas después de la declaración del módulo, en mayúsculas y si el nombre es compuesto se separan las palabras con guiones (-)

El siguiente ejemplo contiene también el tópico anterior.

 

HDL guia 2.png

 

Se acuerdan los estilos CamelCase muy utilizados en la mayoría proyectos de software libre y nosotros lo hemos acordado para:

– UpperCamelCase: Para nombres de módulos, task y memorias.

– lowerCamelCase: Para buses, señales tipo wire y tipo reg.

  • Nombres estándares.

Las señales que aparecen con mayor frecuencia en nuestras descripciones con el reloj y el reset, por lo tanto definimos que deberíamos ambos usar nombres predefinidos para estas señales en nuestros código, clk y reset.

  • Trabajo con Apuntadores (punteros).

Cuando trabajamos en hardware e incluimos aspectos referentes a almacenamiento (como memorias) probablemente nos encontraremos haciendo uso de registros que almacenaran direcciones de posiciones en esas memorias, para identificar rápidamente dichos registros en los códigos fuente; utilizamos el prefijo ptr_ seguido del nombre del registro siguiendo los lineamientos anteriores.

Ejemplo:            ptr_nombreRegistro

 

  • Nombre para los TestBench.

Esto ya no tiene que ver directamente con el código, pero un buen consejo que recibimos de nuestro maestro cuando cursamos Diseño Digital Avanzado es nombrar los archivos de testbench con el mismo nombre del módulo y con el sufijo _tb, por lo tanto si estamos trabajando en un módulo llamado analizador el nombre propuesto para el testbench será analizador_tb.


Eso es todo, son algunas pautas que ayudaran a identificar rápidamente algunos aspectos de los códigos en nuestros proyectos y que son especialmente útiles en la medida en que los mismos crecen en extensión y complejidad (se demuestra al trabajar en software libre).

Si tienes alguna sugerencia para esta guía de estilo no dudes en compartirlo en los comentarios, espero que sea estos ‘tips’ sean útiles en tus proyectos.


Author: Julio César Echeverri M.

Anuncios