imageYou may not be aware that Intel has made publically available on Tianocore an EDKII C Coding Standards specification.  As of this writing, the latest version is 2.0, released in November 2014.  If you’re familiar with earlier versions of this spec, you’ll be pleasantly surprised at the maturity of the present version.

The goal of the coding standards is, to quote from Tianocore:

The EDK II C Coding Standards Specification establishes a set of rules intended not as a constraint, but as an enabling philosophy which will:

  • Establish uniformity of style.
  • Set minimum information content requirements.
  • Allow all programmers to easily understand the code.
  • Facilitate support tasks by establishing uniform conventions.
  • Ease documentation efforts by embedding the design documentation in the code.
  • Reduce customer and new employee learning curves by providing accurate code documentation and uniform style.

Best Parts of the Spec

The spec is well done and I recommend it whole-heartedly.  Here are some of my favorite parts.

 

The “Soft” Sections

A lot of the spec is rules:  detailed commandments describing brace style, declaration of objects, naming rules, etc.  Other parts are more informal sections of prose that anyone, even non-BIOS developers, can appreciate.  These sections are dynamite.  I’m including in my list of the “soft” sections:

§2.1 Software Design

§2.2 Software Maintenance

§5.3.1 Scoping Rules

§6.1 Documentation Concepts

An example from §2.2 Software Maintenance:

Understand the problem before you fix it. The best way to ruin a code base is to fix problems without really understanding them. If your fix is out of context, the next fix in the routine will be four times more complicated. Triangulate the error with cases that should and should not cause the error. Keep at it until you understand the error.

Love it!  It only takes ten minutes to read through these brief sections—check them out.

 

The References

Section 1.4 lists some excellent software engineering resources related to writing good code.  Of special relevance to coding standards is the reference to the Indian Hill C Style and Coding Standard, which I would call the “K&R” of C coding standards.  Like K&R, it too is a product of Bell Labs, the guys who gave us C.  Very well done.

 

Quick Reference

Section 3 is a quick reference to the entire set of coding standards.  This is a nice help, especially considering the spec clocks in at over 70 pages.

 

Doxygen

The spec advocates for use of the Doxygen documentation system.  If you’re not familiar with it, Doxygen is a parsing engine that runs through source code and automatically creates documentation based on the source code’s syntactical elements and a few markup commands.  (like Javadoc, but for C)  The genius of Doxygen is that it takes so little additional effort to create excellent, and accurate, HTML-based documentation.  The accuracy is guaranteed since the documentation is coming from the source code itself.

 

Parts of the Spec I Don’t Like

I really think Intel did a great job, but there are a couple of standards I don’t care for.

 

Tab Spot Size

The Spec insists on a tab size of only two spaces.  I think that’s too small.  The other extreme would be the GNU coding standards, which specify a massive eight spaces per tab stop!  In my experience, both in my own coding and in talking with other programmers about their preferences, four spaces per tab stop is the sweet spot between clarity and wasting space.  A tab stop of only two spaces is too small of a horizontal difference for my eye to make out the hierarchy of the code’s organization, which is the whole point of indentation, anyway.

 

Space Before Parenthesis in Function Calls

Section 5.1.1.2 specifies:

6. Always put space before an open parenthesis. The only exception is macro definitions.
if (...
while (...
EfiLibAllocateCopyPool (...

I’m completely in agreement for if, for, and while statements (etc.), but not for function calls.  Putting the space in there disconnects the function from its arguments and causes my brain trouble.  They should be treated like one unit, with no space.

 

Implementing Coding Standards on Existing Code

What can you do if your organization wants to start using these standards but has a lot of pre-existing code that is non-compliant?  See Uncrustify and Universal Indent—this application can make wholesale stylistic changes to an entire codebase.  The user supplies a configuration file and the tool does the rest.

 

Conclusion

Coding standards for UEFI are especially necessary since our industry is characterized by silicon vendors, IBVs, computer OEMs, and ODM partners all contributing to a common code base.  The standards help improve communication between these disparate partners from different companies located all over the world.

What do you think of the standards?  Leave a comment!

EDKII C Coding Standards Specification

Post a Comment

Be sure to select an account profile (e.g. Google, OpenID, etc.) before typing your comment!