Welcome to the VHDL coding style wiki!

Why should you be interested?

• Be kind to your future self! One day you will need to open an old code and use it, remember do to something or one of punch of other reasons in the end you will do and when you do you will hate that old foul who didn't prepare for this day.
• Be kind to others! We all worked in teams. we all suffered from code integration or solving conflicts. don't make the process harder on others than it already is.
• Who doesn't like elegant code!!

---

Important Notes

• VHDL has a lot of style guides because simply it is not a matter right or wrong there is no "Convention" just people try to make their code look nice and be readable.
• What we will try here is present the options and give a general guide lines to follow. You have to choose what do you think will work with you the most important this is to be Consistent in your code.

---

What we will talk about?

• What your project should look like
• What your source code files should look like
• Naming conventions

---

What your project should look like

The project's structure can help you organize your work, your thoughts and even help your collaboration with others. One suggested structure which is used in some sense in almost every software framework around.
.
|-- Src
|    |-- source_code_files.vhd
|-- Test
|    |-- test_benches.vhd
|    |-- do_files.do
|-- Resources
|    |-- files used by the project like RAM initialization files
|    |-- documents needed by the project\

This kind of structure will help you organize your data very nicely.

---

What your source code files should look like

File Header

• Header comment should contains any information the reader must know about this file
  • Name of the developer
  • Contact information (Email) of the developer
  • The project or assignment goal e.g. Apertus task 1, PWM Chip using I2C interface
• License
  • Even if you added a LICENSE file to your project you should include copyright comment in the header of the source file e.g. Apache 2.0 license header
• Assumptions
  • Sometimes the code is meant to run in a specific environment with specific conditions be clear and write it down

Code itself

• Write a self explanatory code!
  We are programmers. We are logical people let the code reflect that about you. Make the code self explanatory as possible and if the complexity of code is too much here when you should write comments. Remember comments are awesome but too much can make the code unreadable.
• Write comments!
  Comments is essential to understand any code but the more doesn't always mean the better
• Indent your code!
  Indent your code nicely usually between any begin and end statements a tab (or whatever you are using) is required. e.g.

entity x is
    --your code
end x; 

processStyle : process x
    --Declaration
begin
    --Code
end process x; 

• Code blocks size Make your code blocks (Process, Functions, etc...) specialized, concise as much as possible to increase readability and modularity.

---

Naming conventions

• VHDL isn't Case sensitive language so watch out when you are naming stuff.
• Note the data types and built in functions in VHDL is underscore separated that can give you a pretty good idea about the style of VHDL e.g. rising_edge(), std_logic, etc...

VHDL Reserved Words

Since the VHDL language isn't case sensitive we can do any of this formats e.g.

• entity, lower case
• Entity, Upper Case
• ENTITY, UPPER CASE (Not nice for your fingers will typing, a lot of Caps or Shift pressing)\

VHDL Blocks

Entities and Architectures

• Try to make the Entity or Architecture name reflects what it does either behavioral or sequential
• There is no definitive style for Entity but you can choose one of the following
  • FullAdder, UpperCamelCase (if you were Java kind of guy)
  • Full_Adder, Underscore_Separated_Upper_Camel_Case
  • FULL_ADDER, UNDERSCORE_SEPARATED_UPPER_CASE (your code will look very big by the end)

Processes

• Add label to every process if you can.
• Label must be meaningful and related to what the process do

Constants and Generics

It is agreed to write constants and generics in UNDERSCORE_SEPARATED_UPPER_CASE e.g. 'constant BYTE_SIZE'

Signals and Variables

You can choose between to styles

• example_signal, underscore_separated_lower_case (this is more preferable because it is consistence with the VHDL built in functions and data types
• exampleSignal, cammelCase

Input and Output Ports

• you can choose between different styles
  • Treat them as signals and use the same style for both
  • some people like to add suffix for the port name e.g. data_out, enable_in. Your choice.

Suffix

Suffix can be used to indicate some property about the signal

• _in, _out for input and output ports
• _d, _dd for delayed signals
• _v for variables
• _s for state
• _f for functions
• _clk for clock signals
• _n for negated signs
• _a for array types