Quick Thoughts on Creating Coding Standards

Introduction

No team says, "write your code however the heck you want." Unless you are coding alone, it generally helps to have an agreed upon coding standard. Agreeing upon a coding standard, however, can be a painful process full of heated arguments and hurt feelings. This morning I thought it might be useful to first categorize coding standard items before starting the arguments. My hope is that once we categorize coding standard items we can use better decision criteria for each category of items and cut down on arguing. Below are the categories I came up with really quickly with descriptions, examples, and decision criteria for each category. Feedback is welcome in the comments.

Categories of Things in Coding Standards

Language Specific Pitfalls

Characteristics​

  • not subjective, easy to recognize pattern
  • well recognized in the industry as dangerous
  • people have war stories and about these with associated scars to prove it

Examples

  • no multiple declarations on one line in C
  • Cliff Cummings rules for blocking vs. non-blocking assignments in Verilog
  • no willy nilly gotos in C
  • no omitting braces for one liner blocks (or begin-end in Verilog)
  • no compiler warnings allowed

How to resolve disputes on which of these should be in The Coding Standard?

Defer to engineers with best war stories. If nobody has a war story for one, you can probably omit it (or can you?).

General Readability/Maintainability

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." –Martin Fowler

Characteristics

  • things that help humans quickly read, understand, and safely modify code
  • usually not language specific
  • the path from these items to bugs is probably not as clear as with the above items, but a path does exist

Examples

  • no magic numbers
  • no single letter variable names
  • keep functions short
  • indicators in names (_t for typedef's, p for pointers, etc.)

How to resolve disputes on which of these should be in The Coding Standard?

If someone says, "this really helps me" then the team should suck it up and do it. This is essentially the "put the slowest hiker at the front of the group" principle.


Alternatively these can be discussed on a case by case basis during code reviews instead of being codified in The Coding Standard. Be prepared for more "lively" code reviews if you go this route.

Code Formatting

The biggest wars often erupt over these because they are so subjective. This doesn't have to be the case.

Characteristics

  • these probably aren't really preventing any bugs
  • most can easily be automatically corrected
  • are largely a matter of taste
  • only important for consistency (which is important!)

Examples

  • amount of indent
  • brace style
  • camelCase vs. underscore_names
  • 80 column rule
  • dare I even mention it? tabs vs. spaces

How to resolve disputes on which of these should be in The Coding Standard?

Don't spend a long time arguing about these. Because they are so subjective and not likely to cause or reduce bugs one way or the other, nobody should get bent out of shape if their preference is not chosen by the team. Give everyone two minutes to make their case for their favorite, have a vote, majority wins, end of discussion. Use an existing tool (astyle, autopep8, an emacs mode, whatever is available for the language) to help people follow these rules.

Comments

Toby Haynes said…
I'm in favour of all code in main branches of version control system to be automatically formatted using tools like 'astyle' or 'uncrustify' to guarantee a standard layout for code. These same tools can be used to reformat the same code in user branches to user-specific formats, so if a user can't operate with, e.g. 8-space indents and K&R braces, they don't have to. Only at merge points are the standard layout formats required to avoid painful code diffs.
Stefan Birman said…
Hi!
Nice article, as always.

Here are my few thoughts on it:
1) the coding style rule-set is a living creature: it needs to be reviewed from time to time(even if it's once in a blue moon), rules can be added or removed in relation to the engineer's expertise level and tool chain capabilities (simulator capabilities, IDE/editor capabilities etc.)
2) it is important to be able to enforce a coding rule-set using automation. You should never count on mere human discipline. From my experience, discipline doesn't work unless you invest time in code reviews, which are time consuming and don't scale with the project size (not to mention that code reviews shouldn't be about coding style but about algorithm implementation, data structuring, data flows etc).
3) the coding standards can vary from company to company, given the different crucibles of knowledge, experience and toolchain they were created. They can work equally well (i.e. in the advantage of the developers) as long as they are consistently followed. So the main point is: don't look for the perfect coding rule-set, don't look for the 'universal coding set'
4) some companies limit their coding rule-set to the syntax aspects, others go a bit deeper and touch some of the semantic aspects as well (e.g. call tree depth, inheritance tree constraints, limit certain API usage).


/Stefan

Popular posts from this blog

SystemVerilog Fork Disable "Gotchas"

'git revert' Is Not Equivalent To 'svn revert'

Git Rebase Explained