C Coding Style Guide

This is the style guide for COMP2521.

1. C Program Layout
2. Names
3. Layout
4. if, while
5. Declarations
6. Functions
7. Executable Statements
8. Function definitions
9. Structs
10. typedefs
11. Comments
12. Compiler Options
13. Structured Programming
14. No shortcuts
15. C syntax discouraged
16. Security
17. Thanks

C Program Layout

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

1. Header comment
2. #included files
3. #defines
4. local struct typedefs
5. local prototypes
6. global vars (to be used very sparingly)
7. main function (if present)
8. local functions

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

1. Header comment
2. #ifndef guard
3. #included files
4. #defines
5. struct typedefs
6. prototypes
7. (extern) global vars (to be used very sparingly)

A header comment should include:

// Student name and unsw email address
// Tutorial class and tutor name
// Date
// What this file is for (one line summary).

// Possible longer explanation

Names

• all names to be meaningful
• conventions:

  what	convention	example
  functions	camelCase, lowercase first letter, no spaces or _	isCookie (nextItem)
  variables		oldCookieCount = 7;
  anonymous variables (eg some loop counters)	single lowercase letter	i++;
  new typedefed types	camelCase, lowercase first letter unless abstract, uppercase first letter if ADT.	typedef struct positionRep {     int x;     int y; } position;
  constants	UPPER_CASE, words joined with _	#define  MAX_COOKIES 5

Layout

• Use spaces for indents, not tabs
• Indent 3 spaces OR 4 spaces per level, but not a mix in any file
• Describe block structures using indentation, do not rely on { } alone
• MAY include one space before and/or after parentheses delimiting function parameter list
• Use compact { } placement eg

    void eatCookie (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.

if, while

• always use { }, even for single statement blocks

• place opening brace compactly (after condition rather than on following line), eg

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

• use compact braces around else eg

    if (cookies == 0) {
       ....;
       ....; 
    } else {
       ....; 
    } 

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

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

Declarations

• Declare variables at the top of the function

• Declare one per line if initialised. Only use comma separated lists of variables in a declaration when they are related instances (eg int row, col;)

• In a block of related definitions vertically align the names, types, and initialisations
• initialise variables close to where they are first used.
• all structs and enums defined with typedefs
• place prototypes for functions which are only used locally at head of file
• place typedefs for types which are only used locally at head of file
• prototypes and typedefs for functions and types which are used in multiple files are 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
• dont #include a .h file in another .h file

Functions

• put the return type on same line as function name
• should be kept as short, and broken into sub-functions as required
• each function should have a single clearly defined purpose, this purpose should be reflected in its name.

Executable Statements

• one per line, not i=0; j=0;

• use = as an operator sparingly

  • i = j = 0; //NOT OK

  • if ((c = getchar()) != EOF) //OK

Function definitions

• use static for all non-interface functions in library modules
• use prototypes for all functions (even those returning int) (this permits parameter type checking)
• don't turn parameter type checking off in prototypes with (), use (void) instead
• prototypes at the top of the file
• main is to be the first function in the file, function ordering to be roughly top down
• give (sensible) variable names in prototypes

Structs

• typedefs are used to refer to structs

• write struct tags (eg "entryRep" in "struct entryRep" below) in lowercase.

• tags may be used in typedefs and when other typdefs need to forward reference the struct eg in the examples below "struct entryRep" and "struct nodeRep" would not be used again in the program:

  • typedef struct entryRep {
       char *name;
       int  listing; 
    } entry;

    typedef struct nodeRep *Node;
    
    struct nodeRep {
       int value;
       Node next; 
    };

typedefs

• concrete type names start with lower case letter
• abstract type names start with upper case letter

Comments

• students have freedom in use and layout of comments, clarity is the most important criteria

• blocks of comments: style is discouraged. // at the start of each line is preferred.

• tip: be wary of too many inline comments, consider replacing them with a single block header comment.

Compiler Options

• unless explicitly stated otherwise all code should be compiled with

  •    
    gcc -Wall -Werror -O -std=c99

Structured Programming

You may use

• multiple returns from functions
• break
• continue (very very sparingly)

Security

• Submitted code may not contain system calls or file IO unless explicitly permitted.
• Code with security vulnerabilities, such as potential buffer overflows, will be regarded as incorrect and heavily penalised.

Thanks

Parts of the initial version of this document was based on "Appendix C: C Programming Standards" of Programming Techniques using the language C, Government of South Australia, Pearson Education Australia 2005. Subsequently it has been expanded and revised based on the experiences of using it in our courses. It has benefited from the suggestions and comments of numerous 1911, 1921, 1917, 1927 and 2911 teaching staff and tutors. Thank you to all who have contributed.