CSE260 VHDL Style Guide

Getting the computer to understand your code is no guarantee that people will be able to follow it. Just as you would edit an English composition, you should spend time revising your VHDL code to make it elegant and readable. The following guidelines will help you write code that is easy to read and modify.

1. Include a header comment at the top of each file.

• The first lines of the header should include the following standard information:
  1. Your name (and the names of any people you worked with) 
  2. Your email address
  3. The name of the assignment or something that describes why you did this (e.g.," Tutorial 1" or "Full Adder")
  4. The name of the file (e.g., fullAdder.vhd)

• After the standard header information, it's often useful to include a few lines to describing the contents of the file. This should include, for example a brief description of the purpose of the design defined in that file. Be brief and informative. Since the graders and professor are already familiar with the assignment, please don't repeat the assignment. Instead, communicate your approach to solving the problem.

• If you make any assumptions regarding the problem to be solved or about the kinds of inputs or outputs your design will use, you must list these assumptions in a separate paragraph (labeled "ASSUMPTIONS:") at the end of the header comment. Deviations from the assignment should be listed as well. Keep in mind that any significant deviations should also be cleared with the instructor in advance. Specific assumptions regarding particular components or processes may be expressed as inline comments next to the relevant code..

• If you do anything beyond the scope of the assignment, extending the design in some interestng way, be sure to document this at the top of the file, as well. 

2. Write self-documenting code.

• Choose meaningful names for variables, parameters, components and other labels. Use complete words instead of abbreviations. For example, use fullAdder instead of FA. (However, if an assignment specifies a particular name, please don't choose a different one.) Exceptions to this rule would be variables used a loop counters and very long names that could be abbreviated (e.g. forceNextStateToBeReset could be changed to forceToRst). Be descriptive yet concise.
• Use named constants instead of sprinkling numbers throughout your code (except when using the constats '0' and '1'... do not use ZERO and ONE). This not only makes it easier to read the program, but also simplifies changing the values later because you only have to make the change in one place, where the constant is defined. (Test cases are an exception--use numbers there.) Rule of thumb: if a constant is used more than once, give it a name. 
• The logic of your program should be clear from the text. Keep it simple. Avoid "clever" tricks that save a line of code at the expense of clarity.

3. Follow standard formatting conventions.

• Capitalization:

  variable names
  

  the first letter is lower case, with the first letter of each subsequent word capitalized unless the variable names are very short (one or two letters). If short, they can have an initial capital letter

  for example:

  port (I1, I2: in std_logic; carryIn: in std_logic; S, Co: out std_logic); -- standard full adder

  label names
  

  the first letter is lower case, with the first letter of each subsequent word capitalized
  for example:

   fullAdder: process is ...

  
  

  constants

  the entire name is capitalized with underscores ("_") used to separate words
  for example, constant NUMBER_OF_BITS = 4;

  
  

• Indentation:

  begin

  the begin of a block of code goes on a line all its own indented to the level of the block it is associated with.            

code inside begin/end

indent one level for each level inside a par of begin/end statements
example:

		architecture behavioral of fullAdder is
		begin
			S <= A xor B xor Ci;
			Co <= (A and B) or ((A xor B) and Ci);
		end behavioral;

continued lines

when a statement continues across two or more lines, indent the second and remaining lines an equal amount past the start of the first line of the statement.
example:

		architecture behavioral of fullAdder is
		begin
			S <= A xor B xor Ci;
			Co <= (A and B) or 
			      ((A xor B) and Ci);
		end behavioral;

end
            the end off a block of code goes on a line all its own indented to the level of the begin it is associated with. 

if-elsif-else

the statement(s) following an if, elsif, or else should be indented one level. The else and elsif lines should be at the same level as the initial if that initiated the statement
example:

if select = "00" then
    nextValue = "00";
    ...
elsif select = "01" then
    nextValue = "01";
    ...
else 
    nextValue = "11";
    ...
end if;

4. Use inline comments sparingly but whenever necessary.

• Use inline comments whenever the meaning of the code is not immediately obvious from the text. For example, inline comments can be useful to summarize cases in a conditional expression.

     if state = read then             	-- reading the inputs, only
        ...
     elsif state = compute then		-- compute the outputs
        ...
     else                                 -- in some other, or undefined, state
        ...
  

• Whenever possible, write self-documenting code to avoid the need for inline comments. The comment in the following example adds no information and should be omitted since it just wastes the reader's time.

  if reset = '1';  -- if reset is 1
  

5. Present your test cases clearly and methodically.

• Test cases should be ordered logically, preferably in the same order as the code being tested.
  
  
• Whenever possible, choose test cases whose expected output could be quickly computed in your head (without the need for a calculator).
  
  
• When testing small combinational circuits, test all possible combinations of the inputs.
  
  
• For small sequential circuits, test all arcs in the state diagram.
  
  
• For larger circuits, be thorough. Pretend that you are an adversary trying to "trick" the program into giving the wrong answer. For example, test cases should include reset being asserted at the same time the load signal is asserted even if load should never be asserted during reset during normal operation. Pretend this is someone else's circuit and it is your job to break it. However, you are not obligated to test inputs that violate your stated assumptions.

6. Use common sense.