Presentation on creating your own coding style guide. Targeted at VHDL, but also applicable for (System)Verilog and any other language. This slide deck was originally presented by Sigasi CEO Philippe Faes at the 2014 "PLC2 All Programmable Days" in Stuttgart, Germany.

1. Creating your own
coding style
Dr. Ir. Philippe Faes

2. ● What is coding style
● Purpose of a coding style
● Types of coding rules
● Quality criteria for coding rules
● Enforcing coding style
Overview

3. What is a coding style?
Programming style is a set of rules or guidelines used
when writing the source code for a computer program. It is
often claimed that following a particular programming style
will help programmers to read and understand source code
conforming to the style, and help to avoid introducing
errors. [wikipedia]
Brought to attention in 1974 by Kernighan and Plauger
book: “The Elements of Programming Style”
synonyms:
[coding | programming | style] [style | conventions | rules]

4. What is its Purpose?
● Increase readability and maintainability
(= reusability)
● Reduce risk of defects
●

5. Rules severities
Good practice:
Try to avoid this, but we won’t complain if you
break this rule.
Recommendation:
Avoid this. You have to document when you
break this rule.
Strong Recommendation:
Don’t break this rule. No excuses.

6. Useful rules are rules that have important
implications, and there is a good reason for
having this rule, even if there may be
arguments against it.
Arbitrary rules don’t have large practical
implications. Sometimes arbitrary rules are
used for consistency.
Adverse rules don’t have any benefit. The
claimed benefit may be incorrect or outdated.
How to read rules

7. Useful rules: examples
● sensitivity lists
● rules for clock domain crossing
● recommended third-party or in-house libraries
● deprecated libraries
ieee.std_logic_unsigned
● style for Finite State Machines
● reset strategy, initial values of signals or
variables
● allowed / disallowed preprocessor code

8. Arbitrary rules: examples
Usually rules that improve code consistency.
● Capitalisation: UPPER and lower case
● Indentation and whitespace
● Naming conventions like rst_n
● File structure, copyright headers
Formalise what you have.
Don’t overdo these rules.

9. Adverse rules
Many rules that include “weasel terms” like:
○ “... may result in larger circuit”
○ “... may result in slower clock speed”
Ask yourself:
● Is this documented?
○ Can I verify this for my current synthesis tool?
○ Which code snippet and with which tool chain?
=> TEST it yourself
● Is it important?
○ error-free, on time, on budget
versus saving two LUTs or 5% of clock speed
=> use common sense

10. “Some synthesis tools may not support this.”
Ask youself: which synthesis tools?
(not AcmeSynth from 1994?)
If you sell IP cores, you may have to adhere to the
greatest common denominator of current (not historical!)
synthesis tools.
If you build your own design, you should only worry about
your current tool chain, or a few common and modern tool
chains.
Not supported for synthesis?

11. Do NOT start from somebody else’s style book!
● You are prone to copy their errors
● Instead: read a few style books and then put
them away for a week.
● Be critical of rules and validate their reason
for existing
How to start writing
your own style guide

12. Example stylebook structure
● file and directory structure and naming
● file headers, what to put in a file
● naming conventions