Bonnes pratiques

Conventions de nommage, préfixes et bonnes pratiques pour un code VHDL lisible et maintenable.

Pourquoi des règles de codage ?

Dans un projet VHDL réel, un fichier peut être lu par des dizaines de personnes sur des années. Les règles de codage garantissent :

Lisibilité : comprendre le rôle d'un signal au premier coup d'œil
Maintenabilité : retrouver rapidement un bug
Cohérence : même style dans toute l'équipe
Revue de code : facilite la détection d'erreurs

Préfixes de nommage

Ports (interface externe)

Préfixe	Mode VHDL	Signification	Exemple
`i_`	`in`	Port d'entrée	`i_clk`, `i_data`, `i_rst`
`o_`	`out`	Port de sortie	`o_valid`, `o_data`
`io_`	`inout`	Port bidirectionnel	`io_bus`,

io_sda

Préfixe	Signification	Exemple
`c_`	Constante	`c_CLK_FREQ`, `c_MAX_COUNT`
`g_`	Générique (paramètre de l'entité)	`g_WIDTH`, `g_DEPTH`
`t_`	Type défini par l'utilisateur	`t_state`, `t_data_array`
`v_`	Variable (dans un process)	`v_temp`, `v_index`
`P_`	Process (label)	`P_WRITE_FSM`, `P_READ_DATA`
`f_`	Fonction	`f_log2`, `f_parity`

entity uart_tx is
  generic (
    g_CLK_FREQ  : integer := 100_000_000;  -- g_ pour générique
    g_BAUD_RATE : integer := 115_200
  );
  port (
    i_clk   : in  std_logic;               -- i_ entrée
    i_rst   : in  std_logic;               -- i_ entrée
    i_data  : in  std_logic_vector(7 downto 0);
    i_valid : in  std_logic;
    o_tx    : out std_logic;               -- o_ sortie
    o_ready : out std_logic
  );
end entity uart_tx;
 
architecture rtl of uart_tx is
  constant c_BIT_PERIOD : integer := g_CLK_FREQ / g_BAUD_RATE;  -- c_ constante
 
  type t_state is (IDLE, START, DATA, STOP);  -- t_ type
 
  signal r_state   : t_state;                         -- r_ registré
  signal r_counter : integer range 0 to c_BIT_PERIOD; -- r_ registré
  signal r_shift   : std_logic_vector(7 downto 0);    -- r_ registré
  signal w_tx_bit  : std_logic;                       -- w_ combinatoire
 
  -- f_ pour une fonction
  function f_parity(v_data : std_logic_vector) return std_logic is
    variable v_p : std_logic := '0';
  begin
    for i in v_data'range loop
      v_p := v_p xor v_data(i);
    end loop;
    return v_p;
  end function f_parity;
 
begin
 
  P_TX_FSM : process (i_clk)  -- P_ pour les process
  begin
    -- ...
  end process P_TX_FSM;
 
end architecture rtl;

-- Mots-clés VHDL : minuscules
entity, architecture, process, signal, begin, end, if, then, else
 
-- Constantes et génériques : MAJUSCULES ou mixte
constant c_MAX_VALUE : integer := 255;
generic (g_DATA_WIDTH : integer := 8);
 
-- Types : t_ + snake_case
type t_uart_state is (IDLE, START, DATA, STOP);
 
-- États d'une FSM : MAJUSCULES
type t_state is (IDLE, WAIT_START, SEND_DATA, DONE);

-- MAUVAIS : noms non descriptifs
signal a, b, c, x : std_logic;
signal temp1, temp2 : unsigned(7 downto 0);
 
-- MAUVAIS : mélange de styles
signal DATA_OUT : std_logic;    -- incohérent
signal data_in  : std_logic;
 
-- MAUVAIS : pas de préfixe -> impossible de savoir si c'est un registre
signal counter  : unsigned(7 downto 0);   -- registré ou combinatoire ?
 
-- BON : préfixes clairs
signal r_counter : unsigned(7 downto 0);  -- clairement un registre
signal w_carry   : std_logic;             -- clairement combinatoire

Préfixe	Type	Direction / Nature
`i_`	Port	Entrée (`in`)
`o_`	Port	Sortie (`out`)
`io_`	Port	Bidirectionnel (`inout`)
`w_`	Signal	Combinatoire (wire)
`r_`	Signal	Registré (flip-flop)
`c_`	Constant	Valeur fixe
`g_`	Generic	Paramètre de l'entité
`t_`	Type	Type utilisateur
`v_`	Variable	Variable locale process
`P_`	Process	Label de process
`f_`	Fonction	Fonction VHDL

Bonnes pratiques

Pourquoi des règles de codage ?

Préfixes de nommage

Ports (interface externe)

Signaux internes

Autres identifiants

Exemples complets

Conventions de nommage supplémentaires

Casse

Fichiers

Architecture

Ce qu'il faut éviter

Récapitulatif des préfixes

Préfixe	Signification	Exemple
`w_`	Signal non registré - wire, combinatoire	`w_sum`, `w_mux_out`
`r_`	Signal registré - flip-flop, bascule D	`r_counter`, `r_data`