Coding guidlines

Rules for the sake of rules themselves are no usefull. Therefore I will give one or more reasons for each rule.

Rule 1: It is always prossible to ignore the coding guidelines if there are sound reasons to do so.
In chips design 99.9% of your code will be standard, run-of-the-mill. But you will always come across some piece of develish complex logic where you can't achieve the required functionality unless you break the rules. It is good practice to add comments on WHY you broke the rule but then as a good Verilog programmer you are expected to provide lots of usefull comment anyway, certainly if you implement a piece of 'develish complex logic'.


Rule 2: Never use tabs, always use spaces.
There are two reason for this:
Tabs and spaces can be exchanged and give the same apearance but with different contents. That can lead to unchanged code being marked as different in a revision control system.
The apearance of tabs depends on the tab settings of the editor. Your text may look perfectly aligned in your editor but will appear chaotic in an editor with a different tab distance.


Rule 3: There is only one module per file and the filename is the module name + extension.
Verilog compilers offers a great way of building 'libraries'. If there is a missing module (e.g. name 'module') it can be told to look for 'module.v'. Thus all it requires to build a library is a director with modules in it. But that only works if the above rule is folowed.
When working with other people code it is nice if you can find the module instanced. The 'find' command in unix/linux can do that much faster if the filename matches the module name.


Rule 4: Take time to choose your signal names.
They are often the only guidance of what is going on. No matter how clever you are, after doing four big designs in twelve months you will no longer remember what all the signals where for. Long names do not hurt. Especially as nowaday you copy the names aroudn in your editor and do no type them in anymore. (at least I do, I regularly find typos in variables like 'lenght'. But as all the names are the same the design works).   Good practise is to work with positive names. A statement like
read_n <= full_n | (level!=1 && read_n)
seem obviouos when you write it but not when you come back six months later.
If you are like me: when the coding frenzy kicks in you want to get the job done ASAP and a name like 'p' seems as goo as any. Just clean up before you do your first release! Any editor can do a global word substite 'p' for 'polarity'.


Rule 5: Signal names should not change across module boundaries.
This rule is not always enforible, especially if a module is intanced multitple times. However it is a good practice to be able to follow a signal throughout the design hierarchy. A synthesis tool will pick one name for a net no matter how often YOU re-name it. Thus having the same name throughout the hierarchy gives you a high propability that you can find it in the gate level netlist. I once had to trace a reset through a design and found it not only changing name three times but, even worse, changing polarity without changing name. This was code from a big IP provider.


Rule 6: Do not use 'in' or 'out' for port signal names.
(I know there are companies which have just the opposite in their design rules.) This rule is related to the rule above. A signal which is an 'out' in one module will be the 'in' of another. Using 'in' ot 'out' only causes confusion. Renaming 'in' to 'out' between modules is even a bigger NO! NO! (See rule 5) In practice it is always possible to come up with a better name, but it may require some effort. A data bus between two module e.g. a CPU and a memory can be marked as 'data_cpu_to_mem' and 'data_mem_to_cpu' (Or for our mobile phone generation: 'dc2m' and 'dm2c'.) However in general the CPU is seen as the driving force of it all and the names 'wdata' and 'rdata' can be used. Alternative the port names are related to the module. Thus a FIFO has a write strobe and the associated data port is thus named 'wdata'.