CS 241 Coding Standards

1 Coding Standards

All labs must follow the great and hallowed CS 241 coding standards.
These standards do not necessarily represent the best nor the only good way to write C code.
If you have experience programming, then these standards may not be the standards you are used to using.
However, in this class, these are the standards we will use.

2 Primary Reasons for Defined Standard

A standard makes it easier for the instructors to read your code.
A class standard makes it easier for a grader to recognize when a program does not use a consistent standard.
Often when each student is allowed to define his or her own standard, students switch standards multiple times in a single project. It is tedious for a grader to deduce each persons standard and then check for self-consistency.
It is good practice to learn to follow a standard.

3 Naming

All variables not declared const must start with a lowercase letter.
All variables declared with const and #define macro definitions must be all uppercase letters.
All program scope variables must be given descriptive names. For example, use wordCount, charCount, and lineCount, not wc, cc and lc.
Function and block scope variables should usually have descriptive names, but this is not a strict requirement. A character read from a stream is commonly named c. Integer loop indexes are often named i, j, and k.
Never use the single letter l nor the single letter O as a variable.
Function names must be descriptive and start in lowercase.

4 Function Comments

At the top of every function, there must be a comment block with the following information:

/*************************************
* Each parameter’s type and name:
*  input and/or output,
*  its meaning,
*  its range of values.
* Function’s return value.
* Description of what the function
*  does.
* Function’s algorithm
*************************************/

5 File Comments

At the top of .c source file, there must be a comment block with the following information:

/*************************************************/
/* YourFirstName YourLastName                    */
/* Date                                          */
/* What this file is used for                    */
/*************************************************/

6 Open Brackets

Open brackets will be placed at the beginning of a line (not at the end).

/* OK */
if (x == 5)
{
y = y+1;
}

/* Not CS-241 standard */
if (x == 5) {
y = y+1;
}

7 Closing Brackets

Closing brackets will be indented on a line with no other commands. The only exception being comments placed on the line with a closing bracket.

if (x == 5)
{
y=y+1;
} /* Comment here OK */
else if (x == 7)
{
y=y+2;
}

if (x == 5)
{
  y=y+1;
  /* Next line is     */
  /* not 241 standard */
} else if (x == 7)
{
  y=y+2;
}

8 Blocks and {}

Whenever a structure spans more than one line, brackets must be used. For example:

/* OK */
if (x == 5) y=y+1;

/* OK */
if (x == 5)
{
y=y+1;
}

/* Not CS-241 standard */
if (x == 5)
y=y+1;

9 Indenting

Code blocks will be indented to show the block structure with two spaces per level.
Tab characters shall not be used for indenting.
All statements within a block must be indented to the same level.

10 Eighty Character Line Max

No line shall be more than 80 characters.

The best way to avoid overly long statements is by not doing too much in a single statement.

/* Way too long! */
if (getVolume(length1, width1, height1) > getVolume(length2, width2, height2)) printf(”box 1 is bigger\n”); else printf(”box 2 is bigger\n”);

/* Use temporary variables */
int volume1 = getVolume(length1, width1, height1);
int volume2 = getVolume(length2, width2, height2);
if (volume1 > volume2)
{
printf(”box 1 is bigger\n”);
}
else
{
printf(”box 2 is bigger\n”);
}

/* Too long and repeats expression */
if (stack[topOfStack - 1] == ’*’ || stack[topOfStack - 1] == ’+’ || stack[topOfStack - 1] == ’-’ || stack[topOfStack - 1] == ’/’)

/* Much better! */
char c = stack[topOfStack - 1];
if (c == ’*’ || c == ’+’ || c == ’-’ || c == ’/’)

Another case where a temporary variable can shorten a line and improve readability.
Creating the temporary variable c also improves code maintenance:
If the code changes so that the comparison needs to check stack[topOfStack] or stack[topOfStack-2], then the code with a temporary variable only requires a single change while the original requires 4 changes.

There are times when breaking a long statement in to multiple statements is more awkward than keeping the long statement.
In such cases, the statement should be broken in a logical place and each line over which the long statement is continued must be indented.
The indenting must be at least 2 spaces, but can be more spaces it that improves readability. The example below, indents the second line so that the comparisons match up.

/* long line broken without indenting! */
if (commandOption ==’f’ || commandOption == ’c’ ||
commandOption == ’d’ || commandOption == ’g’)

/* indented to line up */
if (commandOption == ’f’ || commandOption == ’c’ ||
commandOption == ’d’ || commandOption == ’g’)

11 Dead Code Elimination

Code that is unreachable or that does not affect the program should be eliminated. This includes:

Dead stores
Variables declared, but never read,
#includes never used
Functions never called.

int foo(void)
{
  int x, i; /* i is never read */
  i = 1; /* dead store */
  x = 1; /* dead store */
  x = 2;
  return x;
  x = 3; /* unreachable */
}

12 Replace Needlessly Deep Nestings

if (c == ’*’) multiply();
else
{
  if (c == ’+’) add();
  else
  {
    if (c == ’-’) subtract();
    else
    {
      if (c == ’/’) divide();
      else error();
    }
  }
}

if (c == ’*’) multiply();
else if (c == ’+’) add();
else if (c == ’-’) subtract();
else if (c == ’/’) divide();
else error();

13 Avoid Code Duplication

Code duplication is when two or more sequences of code are either identical or differ by a small percentage.
Code duplication is generally considered a mark of poor or lazy programming style:
- Contributes to code bulk which interferes with comprehension.
- Cause update anomalies: Any modification to a redundant piece of code must be made for each duplicate separately. At best, coding and testing time are multiplied by the number of duplications. At worst, some copies may be missed, and bugs thought to be fixed may persist in duplicated locations.
Best practice: avoid code duplication with a reusable function or library.

int sum1 = 0;
int sum2 = 0;
for (int i=0; i<4; i++)
{
sum1 += array1[i];
}
average1 = sum1/4;

for (int i=0; i<4; i++)
{
sum2 += array2[i];
}
average2 = sum2/4;

The two loops should be rewritten as the single function:

int calcAverage (int array[])
{
  int sum = 0;
  for (int i=0; i<4; i++)
  {
    sum += array[i];
  }
  return sum/4;
}

14 Keep Function Size Functional

Source code, as it appears on the display, becomes an extension of the programmers mind: it is used to organize, remember, and articulate thoughts.

It is fine for a list of constants or simple statements to scroll off the screen, but when complex logic spans more lines than fit on the display (usually about 40), then the code becomes difficult for a human to think with.

Best practice is to extract logical units from such code and place each unit in a function, even when such functions are only called from one place in the program.

15 Structs

struct Point
{
int x;
int y;
};
struct Point pt;

struct Point
{
int x;
int y;
} pt;

struct Point {int x; int y;} pt;

/* Not CS241 standard */
struct Point {
int x; int y;
} pt;