CS 190 C Style Specifications

Code style is very important -- good style means readable code. Not only does this help you in designing, reading and debugging your own code, but it also allows your TAs and instructor (and future employers) to read, debug and evaluate your code.

Nearly all major programming projects have established conventions for code style. All your assignments will be marked on code style out of 10, using the rubric here. This document is adapted from Francois Pitt's code style specifications for the Winter 2011 offering of CS 190.

Where there is some room for variation within these specifications, consistency is key.

Variable and method names (2 points)

Deduct 1 mark for each violation of the following rules (max 2 marks deducted):

Rule
 Examples
Variables use pothole notation: they start with a lower-case letter and use underscores between words
 double mass_of_tower;
int length;
Constants' names are in all-caps
 const double TAX_RATE = 0.15;
#define SIZE 100;
Functions also use pothole notation
 void delete_element()
double* normalize_array()
Variable and function names should be meaningful; variables tend to have noun-like names, booleans tend to have adjective-like names, and void functions tend to start with verbs
 int length;
int is_sufficient; // boolean
void delete_element();
Exceptions to the above: single-letter loop control variables (recommended: i, j, k, n, m), and temporary variables that are used only for reading input (recommended: f, h, g)
 f = fopen("data.csv", "r");
for(i; i < 10; i++)


Indentation and braces (2 points)

Deduct 1 mark for each violation (max 2 marks deducted).

Rule
 Examples
Code should be indented with Allman-style indentation: a new line for each brace. Braces should be aligned with the block that they open/close. Content inside a block should be indented.
 while (thing)
{
    if(condition)
    {
        foo();
    }
}


Whitespace and "chunking" (2 points)

Deduct 1 mark for each violation (max 2 marks deducted).

Rule
 Examples
Operators should have blank spaces to the right and left
 1 + 3 instead of 1+3
Lists should have spaces after each comma
 call_function(2, 3, n)
Each function and struct definition should have two blank lines after it
 void foo()
{
        return 0;
}


void bar()
{
        return 1;
}
Each loop or selection block should have one blank line afterwards
 if(condition)
{
        stuff();
}

int z = 3;
Code should be appropriately "chunked" (blank lines used to separate chunks of code which go together, like paragraphs in an essay). Beginning each chunk with a comment outlining the chunk is recommended.
 // Here we calculate the total:
int sub_part = get_sub_part(thing, stuff);
int total = sub_part + other_thing;

// Now we calculate the average
double sub_size = get_size(thing, stuff);
double other_thing_size = get_size(other_thing);
return total / (sub_size + other_thing_size)


Documentation and comments (2 points)

Deduct 1 mark for each violation (max 2 marks deducted).

Rule
 Example
Each file has documentation at the top of the file indicating the filename, what the file contains, who wrote it, and when it was written.
 /* subway.c -- simulates the TTC using linked lists. Elizabeth Patitsas, Dec 3, 2012 */
Each method should open with a comment: a summary of what the method does, what each input is (and need to be), what it returns, and pre/post conditions.
 int generate_number(int max)
{
    /* Generates a random number (int), which is between 0 and max. Takes max as a parameter; assumes max is >0.
    Pre: max > 0
    Post: generated number is between 0 and max */
}
Comments should be sufficient that a reader can understand the gist of your code by *only* looking at the comments -- but comments should not be excessive to the extent where the reader has every line described for them. We recommend a comment at the beginning of each "chunk" of code (approx every 4-6 lines). Comments are more readable when placed on a line of its own, on the line /above/ the code it refers to
 // and now we calculate the average
double total = get_total(params);
double length = get_length(params);
double average = total / length;


Organization (2 points)

Deduct 1 mark for each violation (max 2 marks deducted).

Rule
 Example
Each file is structured as such:
  1. Documentation
  2. Any include statements
  3. Any globals
  4. Any method headers
  5. Any methods. If there is a main method, it should be either first or last.
 /* example.h -- Example header file. Elizabeth Patitsas, Dec 3, 2012. */

#include "thing.h"
#include "stuff.h"

const int MAX_SIZE = 1000;

int foo(int variable, double number);
double bar();
The methods in a file, as well as method headers, are organized in a sensible fashion.
 void insert_node(struct node* root, struct node* to_insert);
void remove_node(struct node* root, struct node* to_remove);

void print_node(struct node* root);
void print_tree(struct node* root);
Numbers or other values used multiple times should each have a variable, rather than repeatedly recalculating them, or referring to a "Magic Number"
 double avg = total / num;
rather than referring to total / num repeatedly
No superfluous control flow.

Control flow should only be managed by loops, conditions, returns and function calls (goto statements and break statements are not allowed).

Statements like "while(1)" or "if(0)" may never be used and are terrible style.
 if(condition)
{
    return z;
}
return y;

instead of:
if(condition)
{
    return z;
}
else
{
    return y;
}

Another example:
return x == NULL;

instead of:
if(x == NULL)
{
    return 1;
}
else
{
    return 0;
}
Generally speaking, each program statement should be on a separate line, unless there is good reason not to. No line in any code submitted should ever be more than 80 characters long.