C and C++ coding conventions

I've seen as many styles for C as many times I've been on C-based projects. I've picked up a lot of conventions from different people and experimenting with what I find most readable after I'm away from the code for a few days. I've also probably spent as long thinking up the best way to write code as I have on interface design, so most of these aren't arbitrary in the slightest.

There are a lot of guidelines that relate specifically to C++, but the overlap of the two languages makes it silly to present them separately. However, I will try to indicate when possible if a convention applies to a specific language.

Table of Contents Formatting Files and file naming Interfaces Classes (C++ only) Implementation files Functions Conditionals and loops Variables Comments

Formatting

• Lines are absolutely no longer than 72 characters. Where applicable I will try to provide strategies for splitting lines should you run over the limit.
  • NOTE: I've often heard this guideline because it's the width of a normal letter-sized page with reasonable margins. Additionally for myself, I often code on a 10.2" netbook screen (because I'm a crazy person) and 72 characters is exactly the width of a vertically split emacs buffer on my screen.
• Use camel-case for file, class, function, variable names, and most anything else that needs naming. The only time that I don't use camel-case is for constant values, for which I use all caps with underscores separating words/tokens.
  • NOTE: I know that camel-case isn't as readable as underscores, but camel-case is much easier to type.
• For dates, Use the numerical date, a three to four word abbreviation for the month, and the year
  • Example: 17 Sept 2011
• Tab characters are evil. Instead use 4 spaces. Generally any good text editor can be set to insert 4 spaces when pressing the tab key.

Files and file naming

• Header (aka interface) and implementation files should be separated. The only exception is in C++ when using template classes. Of course this is a restriction of most compilers since generally type variables have to be initialized all at once across the class declaration and definition.
• Header files should have a '.h' file extension for both C and C++.
  • There is a '.hpp' extension for C++ header files, but many big projects use '.h' anyway, including Google. Just as a side note, Google has a very extensive C++ style guide themselves from which I picked up some conventions myself.
• Implementation files ('.c' or '.cpp') should match the name of the associated header.
  • This is pretty standard, but it bears mentioning.
• For library-style modules, use a camel-case name starting with a lower-case letter. Try to use a descriptive name for the library.
• For C++ classes, name both the header and implementation file after the class it defines using camel-case starting with a capital letter.
• All files need to have a header (following the license, if applicable) that consists of the following parts:
  • File name
  • Project name
  • Author(s) and email address in parentheses
    • For multiple authors, list each one on a new line starting after "Written by" line. Indent four spaces (no tab characters) from the "Written by" line.
    • Should an author line exceed the 72 character limit, put the email address on its own line indented an additional four spaces.
  • Organization information, if applicable
    • For school projects, I include my school (Indiana University), course name and/or catalog number, and semester
  • Creation date and responsible author
  • Date of last update and responsible author
  • Short description of the file's purpose
• Headers are written using the block comment style (/* ... */), with the first line consisting of the opening forward slash (/) and 70 asterisk (*) characters, followed by the appropriate information (described above) with each line starting with a space, one asterisk (*), and another space. Similar to the opening line, the last line of the header consists of 70 asterisks (*) and the closing forward slash (/).
• An example header:

/********************************************************************** 
 * example.h 
 * Example project 
 * Written by Chris Frisz (cjfrisz@chrisfrisz.com) 
 * Friszy Productions, Inc. 
 * Created 17 Sept 2011 by Chris Frisz
 * Last updated 17 Sept 2011 by Chris Frisz
 *
 * Defines the interface for the example library. If there was 
 * anything interesting to explain about the library in general, I 
 * would put it here.
 **********************************************************************/

Interfaces

• Always use include guards for interface files. The symbol passed to #ifndef and #define should be the name of the file with the period replaced with an underscore. Additionally, the symbol should be prepended and appended with a double underscore (__). For example (assuming the interface file example.h):

#ifndef __EXAMPLE_H__
#define __EXAMPLE_H__
  [ Whatever code appears in the interface ]
#endif

Classes (C++ only)

Implementation files

Functions

Conditionals and loops

Variables

Comments

---

Back to Coding conventions