Verilog Coding Guidelines- Part 5

5. FILE STRUCTURE

5.1 One file, one module

Create separate files for each modules. Name the file .v. The only exceptions for this
file naming convention shall be the technology-dependent modules (top module or macro
wrapper modules). These files shall be appropriately named like design_name_fpga.v, design_name_tsmc.v, or design_name_virtex.v.

5.2 File header

Each source file should contain a header at the top of the file in the following
format:
/////////////////////////////////////////////////////////////////
//////////
//(c) Copyright 2008 Verilog Course Team/Company Name. All rights reserved
//
// File:
// Project:
// Purpose:
// Author:
//
// $Id: index.html,v 1.1 2008/0773/23 01:55:57 VCT $
//
// Detailed description of the module included in the file.
//Include relevant part of the spec
// Logical hierarchy tree
// Block diagrams
// Timing diagrams etc.
//
/////////////////////////////////////////////////////////////////

The above example is for verilog. Change the comment characters appropriately for other source types. Example: "#" in Tcl, Perl and CSH. The presence of variable $Id$ in the header will capture the filename, user, version information every time the file is checked-in/committed.

5.3 Modification history

Each file should contain a log section at the bottom of the file in the following format:
///////////////////////////////////////////////////////////////////////
////
//
// Modification History:
//
// $Log$
//
///////////////////////////////////////////////////////////////////////

Listing the modification history at the top of the file can be annoying as one has to scroll down to reach the code every time the file is opened for reading. The variable $Log$ will cause RCS/CVS to capture the user-comments entered during each check-in/commit as comments in footer section.

5.4 Include Files

Keep the `define statements and Parameters for a design in a single separate file and name the file DesignName_params.v