You gotta have style — a C style sheet

Every C programmer, and every programming team that uses C, must have a C style sheet — a description of how the C program will look. At a minimum, the C style sheet is a page or two detailing how program elements are named and indented, use of braces, etc. More sophisticated “programming” guides could have 50 or 100 pages; they may include rules/restrictions regarding C types, operators and statements.

Those readers who use a written coding style may skip to the end.  (If you tend to follow a style, but you do not have a written style sheet, you may not skip to the end.)

Begin Rant….

I claim every programmer “must” have a C style sheet because without one there can be no consistency. Without a style sheet, programming projects developed by a team would suffer from the idiosyncrasies of individual programmers. Without consistency, even code created by a single programmer would be chaotic.

Is code consistency really so important.?  YES. It’s difficult to cooperate with other programmers if code is developed with multiple styles (or no style at all). Design reviews become more laborious; the code style becomes a distraction in the review process or worse becomes a source of disagreement. Does anyone really think that a heated discussion of the proper indentation of braces makes finding “bugs” any easier? (Unfortunately, I’ve been present at such a design review more than once.)

You say you don’t work in a group; you write code only by yourself. A consistent coding style is still important. If you can’t or will not write the code in a consistent style, how can programming be improved?  How can you notice the techniques that were insufficient to prevent mistakes?  Code must be written consistently before there can be any improvement in programming results.

This is the end of the rant.

Are you looking for a few ideas?  I’ve found the following things to be useful in a C style-sheet

  • Set Code Indentation
    The style sheet should specify the number of spaces for each level of indentation.  I’ve heard that studies have shown that an indent of 3 or 4 spaces is ideal.  The style sheet should also state that the indentation should always be done with spaces and not Tab characters.  (Tab characters actually mess up formatting.)
  • Specify use of braces for compound statements
    I hate searching for the beginning of a code block.  Some programmers put the opening brace at the end of a text line; this can make matching opening and closing braces time-consuming.  The style sheet should specify that the closing brace always is located directly below the opening brace.
  • Show the difference between a variable and a defined constant
    I would love to get back all the time I’ve spent trying to determine whether the text I’m reviewing is a variable or a defined constant.  The style sheet should have a naming convention that clearly distinguishes between defined constants and declared variables.  It’s helpful to know whether the variable is ‘static’ or not.
  • Is the function local (in the same file) or defined in another file?  What file?
    I know that code editors can find function declarations quickly, but it adds to understanding if the code reader can instantly know whether the call is within the file (and therefore has access to file-scope static variables) or is external.  A naming convention in the style sheet can make this clear.
  • Code Comments should be consistent across the entire project
    The style sheet can make this happen.  A few sentences can describe how and what type of comments are required to document procedures, structures, the values in an enumerated type.

If I’ve convinced you to do something but you still do not know how to start, I’ve posted a Simple Style Sheet on the website.  It’s a very basic style sheet, but it’s a major improvement over no style sheet.

CoAutomationSimpleCStyleGuide-updated

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>