Style Guide for C/C++ Programming

Version 1.2. Last Revised: January 11, 2016

This document describes the style guide for C and C++ programming used in my programming classes at Vermont State University. Conformance is encouraged for all C and C++ programming done in any of my VTSU classes.

This guide is not intended to cover all aspects of style that might be defined. One can still write poorly styled programs while following this guide. Instead, this guide is intended to cover essential issues so that students who are not experienced with any particular style develop good habits from the start. By adopting a standard style, I also hope to simulate the formality of some professional programming environments and facilitate the work of other instructors, tutors, and peers who wish to help students with their programs.

In this document, the word "SHALL" is used to indicate a requirement of this guide. The word "SHOULD" is used to indicate a recommendation of this guide. The word "CAN" is used to indicate an allowable option.

Spacing and Indentation

Spaces SHOULD be used around binary operators, after (but not before) commas and semicolons, and immediately inside parenthesis. This rule can be broken if doing so helps to clarify complex expressions. As an exception, spaces SHALL NOT be used around the '.' and '->' (and for C++ the '::', '.*', and '->*') operators.
```
  /* CORRECT */
  if( ( input = fopen( "somefile.txt", "r" ) ) != NULL ) { ...
```
No spaces SHOULD appear immediately after the opening keyword of a control structure, inside square brackets used for array access, or between a unary operator and its operand.
```
  /* CORRECT */
  for( i = 0; i < 10; ++i ) a[j]++;
```
The braces that open and close a function SHALL appear in column one on lines by themselves.
```
  /* CORRECT */
  int main( void )
  {
    printf( "Hello, World!\n" );
    return 0;
  }
```
Every statement in a block SHALL be indented a uniform amount beyond the code in the enclosing block. We recommend an indentation depth of four spaces, but any amount is acceptable as long as it is applied uniformly. Braces SHALL follow one of the two styles shown below. The first style is preferred.
```
  /* CORRECT (Closing brace aligns with keyword that opens block) */
  if( x == y ) {
      printf("They are equal!\n");
  }

  /* ALSO CORRECT (Braces both indented to the same level as keyword) */
  if( x == y )
  {
      printf("They are equal!\n");
  }
```
Once a pattern has been chosen for (non-function) blocks. It SHALL be followed consistently throughout the source file.
Statements inside each case of a switch statement SHALL be indented in the same manner as described for blocks. This includes the break statement at the end of the case, if any. The case statement itself SHALL NOT be indented relative to the switch.
```
  /* CORRECT */
  switch( Value ) {
  case 1:
      printf( "Value == 1!\n" );
      break;
  }
```
Structure and class definitions SHALL be treated like any other block. The "public" and "private" headers (C++ only) SHOULD be treated the same way case statements are treated.
```
  /* CORRECT */
  class Example {
  public:
      Example( );
     ~Example( );  // Note indentation exception for destructor declaration.
  private:
      int x, y, z;
  };
```

Names

Names SHALL be meaningful and, except in unusual cases, SHALL be normal English words (or well-known abbreviations) spelled correctly. An exception to this rule is allowed for variables that are the indices of for loops. Integer loop indices CAN have one of the single letter names i, j, k, etc. If a for loop is using a pointer (or iterator) as a loop index, that variable CAN be given a name such as p, p1, p2, etc.

Names such as 'x' and 'y' CAN be considered meaningful in certain cases (such as in a program that is manipulating Cartesian coordinates), but they are usually not meaningful.

Names that are traditional in the problem domain are considered meaningful. For example, a two-dimensional array holding the coefficients of a system of linear equations can be called 'A' because of the widespread use of the matrix equation 'Ax = b' in the literature of such systems. In addition, names that appear in references are also acceptable even if they normally are not meaningful. For example, if the description of an algorithm in a book uses 'x' and 'y', you can also use 'x' and 'y' as names to make the connection between your code and the book easier to follow. In this situation, you SHALL also provide a proper reference to the book in the comments.
Macros, const objects, and enumerators SHALL be given names consisting of entirely uppercase letters.

File Layout

At the top of each source file, there SHALL be a comment header containing (at least) the name of the file, the name of the programmer(s), a relevant date, and a brief description of the file's contents. The comment SHOULD be formatted in a manner acceptable to the Doxygen documentation extraction tool.

Here is a template of an appropriate header comment block.
```
/*! \file   awesome.c
 *  \brief  A very awesome program.
 *  \date   January 11, 2016
 *  \author Jill J. Jones <JJones@vtc.vsc.edu>
 *
 * This program illustrates something very awesome. Here is where I explain
 * just how awesome it is. Once you use this program your life will be changed
 * forever. Tell all your friends!
 *
 */
        
```
At the top of each function, there SHOULD be a comment header that contains at least the purpose of each parameter, the meaning of the return value, the pre- and postconditions (if any), and a description of what the function does. The function main and trivial functions are exempt from this rule. The comment SHOULD be formatted in a manner acceptable to the Doxygen documentation extraction tool.
Source lines SHOULD be 96 characters wide or less.
Tab characters SHOULD NOT be used in the source file. Indentation SHOULD be made using spaces.
The source file SHOULD be formatted so that it looks appropriate with a constant width font.

Printing

Source code SHALL be printed using a constant width font.
Source lines SHALL NOT be wrapped, nor shall they be truncated.
There SHALL exist a "reasonable" margin at the top and bottom of every page and along the left edge of every page. The margin SHOULD be large enough so that the pages can be put into a three-ring binder (or other binding system) without losing any information.
Pages CAN be numbered and CAN each have a header and/or footer.

Other Items

Some instructors may allow you to copy code fragments from other sources into your programs (check with your instructor before doing this). If you do copy code fragments, they SHALL be referenced properly in the comments of your program.