Coding Guidelines For C and VHDL

• Use descriptive identifier names (not S0, S1, j, k, etc.)
• Pin names from manufacture’s datasheets and provided entities
  (e.g. D(7 downto 0), Q, Cin ) may be acceptable
• Paragraph (indent) your code
• Break long lines and keep it readable (look at your printouts!)
• control the amount of indentation and size of tabs; small indents don’t rob you of space to put your code
• Use blank lines and other white space
  
• Use consistent capitalization
• Avoid "Magic Numbers" (numbers throughout your code)
• declare and use constants and generics so your code is portable and maintainable
• Put constant and component definitions in packages
• (saves typing too)
• Use hierarchy to your advantage
• reuse code
• use provided library code as much as possible.
  
• -- /* Use comments */ --
• Start each file with a comment block, including entity names, author(s), date, project/lab, description.  Note what work it is derived from, if any, and what has changed.
  
• Describe in general terms what each function/architecture/subprogram does with a comment block
  
• Define non-obvious identifiers
• Explain tricky pieces of code
• Don’t hand in "commented out code"
• Use vectors, arrays and other datastructures to simplify code
• Use provided data structures/classes or create new data structures/classes as appropriate. 
• Keep function call /portmap parameter lists small
• (reduce code size, reduce human error, improve readability)
•  Avoid global variables
• Correct code is always important, avoid logical errors
  

C

• Do not ignore return values that report errors.
• All calls to malloc or other allocator must be matched with calls to free unless you can demonstrate /* and comment */ that you need to retain this memory forever.
• Lack of awareness of memory management in embedded systems kills free memory and your project. This usually shows up when student attempts to allocate giant automatic arrays on the stack without paying attention to how big the stack is. Sometimes allocating in the heap produces the same result. Recursive calls can also exhaust the stack.
  
• You can find some GNU wisdom (not a requirement for this course) in http://www.gnu.org/prep/standards/standards.html#Writing-C

VHDL

• Use named association in port map’s
• e.g. port map ( clock => clock, d => stage1, q => stage2)
• (positional association is harder to debug)
• Use VHDL 93 syntax extensions
• make effective use of optional labels at end of entity, architecture, process
• In clocked architectures, outputs are best clocked
• Use Moore finite state machines
• This avoids building long combinational paths between architectures