Computing 1 Style Guide

1. C Program Structure
2. Names
3. Layout
4. if, while
5. Declarations
6. Functions
7. Structs
8. Comments
9. Compiler Options
10. Thanks

C Program Structure

• In a C program file items should be arranged in the following sequence:

1. header comment
2. #included files
3. #defines
4. local struct typedefs
5. local prototypes
6. global variables (only if absolutely necessary)
7. main function (if present)
8. local functions

• In a C header (.h) file items should be arranged in the following sequence:

1. header comment
2. #included files
3. #defines
4. struct typedefs
5. prototypes
6. (extern) global variables (only if absolutely necessary)

A header comment should include:

// Name, Student Number.
// Date.

// What this file is for (one line summary).

// Possible longer explanation, copyrights, etc.

Names

• all names to be meaningful
• functions and variables like this: varName or var_name
• constants in all uppercase, e.g. LINE_LENGTH
• single letter integers like i,j,k may be used for loop counters and array indices.

Layout

• use spaces for indents not tabs.
• indent either 2, 3 or 4 spaces per level, but not a mix in any file.
• indentation must be used to describe block structures, do not rely on { } alone.
• MAY include one space before or after ( for function parameter list.
• use compact { } placement e.g.

    int eatFood( int age ) {
       printf( "Yummy" );
    }
  

• no lines over 72 characters, (clearly) reformat expressions and comments as required to fit this limit.
• no space before commas in parameter lists, at least one space afterwards.
• only one statement per line (except in extreme circumstances)

if, while

• always use { }, even for single statement blocks
• place opening brace compactly (after condition rather than on following line), e.g.

    while( hits == 0 ) {
       ... ;
    }
  

• do not further indent chained else if and else statements eg

    if( hits == 0 ) {
       ... ;
       ... ; 
    }
    else if( hits < 10 ) {
       ... ; 
    }
    else if( hits < 50 ) {
       ... ; 
    }
    else {
       ... ; 
       ... ; 
    }
  

• don't use single = as a conditional, i.e. if(x = func(y)) ...

Declarations

• variables are declared at the top of the function.
• declare one variable per line if initialized; only use comma seperated lists of variables in a declaration when they are related instances (eg int row, col;)
• in a block of related definintions vertically align the names, types and initializations
• variables should be initialized close to where they are first used.
• all structs and enums defined with typedefs
• prototypes and typedefs for functions and types which are only used locally at head of file
• prototypes and typedefs for functions and types which are used in multiple files should be placed in a meaningfully named .h file, which is included in the file in which the function is defined and also in each file which uses the function or type.

Functions

• put the return type on same line as function name
• should be kept short, and broken into subfunctions as required
• each function should have a single clearly defined purpose, this purpose should be reflected in its name.
• main is to be the first function in the file
• main should be preceded by prototypes of all other functions in the file (including those returning int)
• must give (sensible) parameter names in prototypes; if a function takes no parameters, include ( void ) in the prototype

Structs

• typedefs should be used to refer to structs; the word "struct" should not occur in the body of the program
• the typedef should have the same name as the struct but with the first letter in uppercase, e.g.

    typedef struct node Node;
  
    struct node {
       int   val;
       Node *next;
    };
  

Comments

• students have freedom in the use and layout of comments, clarity is the most important criterion
• one-line comments should use // rather than /* */
• for multi-function programs, comments which support automatic documentation systems such as doxygen are encouraged
• consider using a block header comment at the beginning of a function or block rather than a large number of in-line comments
• comments are particularly important for explaining anything unusual in your code
• avoid commenting on things which are blindingly obvious, i.e. don't do this:

      x = y + z; // set x to be equal to y plus z
  

Compiler Options

• unless explicitly stated otherwise all code should be compiled with

      gcc -Wall
  

• for debugging, you may like to use dcc instead of gcc

      dcc -Wall
  

• if the code takes a long time to run, re-compile it using the optimization option

      gcc -Wall -O
  

  (or -O2 or -O3 if you need even more optimization)

Thanks