Creating your own coding style

Creating your own coding style

• 1.
  Creating your own codingstyle Dr. Ir. Philippe Faes
• 2.
  ● What iscoding style ● Purpose of a coding style ● Types of coding rules ● Quality criteria for coding rules ● Enforcing coding style Overview
• 3.
  What is acoding 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 itsPurpose? ● Increase readability and maintainability (= reusability) ● Reduce risk of defects ●
• 5.
  Rules severities Good practice: Tryto 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 arerules 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 Usuallyrules 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 rulesthat 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 toolsmay 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 startfrom 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