Coding Standards

Table of Contents

You will be creating several types of files to complete the laboratories in this course (SystemVerilog, Tcl, etc.). You are required to adhere to a number of coding standards for all file types as well as language specific coding standards for all files you submit for your ECEN 320 labs. Your code will be reviewed by a TA based on these coding standards, and you may lose points on your submission for failing to follow these coding standards. This document is broken up into General Coding Standards for all files created independent of the language and Language Dependent Standards that specify standards specific to each of the languages for which you create code or files.

Each coding standard has an acronym that will be used during grading. Your feedback on coding standard violations will include the coding standard acronym instead of a detailed description of the violation. Refer to this page for details on the coding standard acronyms.

General Coding Standards

  • G1: Any code you submit must be submitted as a plain ASCII text file. Files with non-binary characters are not accepted. If you can open your file with a conventional text editor and view its contents then the file is probably a text file. As a plain ASCII text file, your file should not have any non-printable control characters anywhere within the file (these characters sometimes show up as boxes or symbol characters in a text editor).

File Header

G2: Every code file submitted as part of the labs must have a ‘header’ using the language specific comment mechanism (some generic text, non-code files may be required that do not require a header). The header of every file must include each of the following items:

  • G3: Opening and Closing Line: Provide a line of characters to signify the start of the comment. Provide a line of characters to signify the end of the comment
  • G4: Filename: clearly specify the filename of the file
  • G5: Author: Put your full name (matching your learning suite name)
  • G6: Description: Provide at least one sentence describing the purpose of the file.

The example below demonstrates an example basic header for a SystemVerilog file:

/***************************************************************************
* 
* Filename: filename
*
* Author: <Your Name>
* Description: <Provide a brief description of what this HDL file does>
*
****************************************************************************/

Additional items for the header may be added for different file types or for lab-specific situations.

White Space

G7: Sufficient white space must be provided to make the file easy to read.

White space (extra empty lines) is often used to break up text files and make them more readable. Code that is crammed together without any white space is hard to read and messy. Every source file must have ample white space to separate sections of your code into easily distinguishable code regions. Some language coding standards have specific white space requirements. Your code may be penalized if there is insufficient white space that makes the code difficult to review or read.

Line Length

G8: You should not have lines that are longer than 90 columns. If you have a line of code that is getting long, make sure you end it and finish the logic/code on the next line. Source code that is longer than ~90 or so columns can be difficult to read and maintain.

Indentation

G9: Indentation will be used in the code to show its structure. It should be clear from the indentation which structural element the text is a member of.

System Verilog Coding Standards

HDLs (Hardware Description Languages) like SystemVerilog can be difficult to understand. To make SystemVerilog code more readable and maintainable, you are required to follow strict coding standards. These standards are explained below. Each and every lab will be graded against this coding standard.

Files

  • S1: A new .sv file will be created for every SystemVerilog module you create. Only one module may be defined in a single ‘.sv’ file.
  • S2: The name of any SystemVerilog file you create must match the name of the module it contains. For example, if you have a SystemVerilog file with a module named FourFunctions, the filename will be FourFunctions.sv.

Signals

  • Signal types:
    • S6: Declare module inputs as input logic
    • S7: Declare module outputs as output logic
    • S8: Declare internal signals as logic
    • S9: The keywords reg, wire, and var are not allowed to be used
  • Signal names:
    • S10: Use descriptive names (e.g. clrTimer instead of n7).
    • S11: Use an _n suffix for active low signals (e.g. write_n).
  • S12: When signals are declared, they will not use an initializer. For example, this is incorrect: logic nextState = 0;. Rather, signals will be declared as in logic nextState;. If you want a signal to initialize to some known value, provide a control signal (like clr) which will set it to that value.

Comments and Indenting

  • S14: Each always_ff block and every always_comb block will be preceded by a comment describing its function and how it should operate.
  • S14: Each module instantiation should be preceded by a comment describing its purpose.
  • S15: If the name of a signal is expressive enough (e.g. clrTimer) then a comment describing may not be needed. Otherwise, all signal declarations will have an associated descriptive comment. Be careful – what is considered “descriptive enough” is subjective. Every semester students lose points because they think that n5 is descriptive but the TA does not. Err on the side of descriptive names or just always add a comment that tells what each signal is for.

Design Requirements

  • S16: The only assignment operator allowed in an always_ff block is the <= operator. The only assignment operator allowed in assign statements and always_comb blocks is the = operator.
  • S17: Every always_comb block must begin by assigning default values to all signals being driven in the block.
  • S18: Every always_ff block will include functionality allowing the registers within the block to be set to known values via the assertion of a clr or load signal. The exception to this may be something like a shift register which will eventually shift in known data and therefore which does not necessarily require an explicit clr or load signal.

Style

  • S21: The code for the different sub-modules in a module will be grouped together. For example, the statements associated with the timer circuitry will appear together, followed by the statements associated with the bit counter circuitry, followed by the state machine. Each such section of circuitry will have comments delimiting it.
  • S22: Local signal declarations will come just after the module definition and its port declarations.
  • In programming (as well as HDL-based design) there are two common ways of naming signals so that their meaning is obvious.
  • One way is called camel case and consists of starting the signal name with a lower case letter and then capitalizing subsequent words as in: clearTimer, resetConfigurationRegisters, or launchMissile.
  • The second way is to make everything lower case and use underscores to separate the pieces as in: clear_timer, reset_configuration_registers, and launch_missile.
  • Choose one of these two styles, be consistent, and use descriptive signal names.
  • S23: Similarly, there are common ways of naming modules and constants. Modules will start with a capital letter as in: EventCounter or InitializationRegisters. For constants (sometimes called parameters in SystemVerilog), they will be uppercase as in INITVAL, THRESHOLD, or DATAWIDTH.

Conclusion

Why would any of this be important? This is the way that design is done in industry (except their style rules are much more extensive and may take many pages to describe). In a large design with millions of signals and thousands of modules, this adds uniformity to the design to help make the code more readable, understandable, and maintain-able.