ECE Logo

EE 312 - Software Design and Implementation I

UNDER CONSTRUCTION

C and C++ Style Guide for EE 312

Program style, or hygiene, involves a program's readability and its logical structuring. It is very important. Hygiene is useful so that you can look at your own code months or years after you wrote it, and still find it readable. It's important to the graders who are reading and making sense of your program. Organizations that produce quality software typically have style guides.

Your programming assignments will be graded on hygiene as well as correctness.

Currently, the style guide contains rules for C program style. Once we start programming in C++, it will be updated. Note that until C++ is introduced in class, you must be writing your programs in C, not C++.

1. Do not capitalize the first letter of methods or variables.

void methodName() { }
int num1 = 3;

Use camelBack style (eachWordAfterTheFirst starts with a capital letter) for variable names. For function names, use either camelBack or separate multiple words with underscore characters (do_something).

2. Use comments.

Comments should not be excessive - you should not include a comment for every statement. You should include a comment that summarizes what a function does, as well as comments for long or confusing parts of your code.

/* Here's a comment summarizing my function  */
void methodName() { 

    /* This tricky part of my code does blah, blah */

}

Include a comment at the top of your program that includes:
  • Program author
  • Date
  • A brief description of what the program does

3. Indent.

The body of a function or block should be indented 3 or 4 spaces. All function definitions should line up with each other. Be consistent with indentation.

for(i = 0; i < numCases; i++) {
    /* Ident the for loop body */
    printf("%d\n", i);
}

4. Use meaningful variable and function names.

int numTokens;
double hypotenuse;

Don't use double h; or int nT - they are too vague. But also don't use ten words in one variable - that's too much.

It's ok to use x or y to represent coordinates. It's also ok to use i, j and k (but not lowercase l) for loop control variables if they are simply counting out steps of the loop. However, if the loop control variable has more meaning, then give it a more meaningful name. For example, if the loop control variable represents mass in pounds use massInLbs instead of i.

5. Use constants for constant values.

6. Use a consistent brace style.

For functions and blocks, use either of these two brace styles, but choose one and use it consistently.

int main(void) {
   
    /* indented code goes here */

}  // main

OR

int main(void)
{
    /* indented code goes here */
}  // main

7. Limit the scope of variables and constants to the smallest necessary.

8. Structure and removing redundancy.

Use functions (and later, classes) to provide structure to your program and remove redundancy. A function should do one thing. Functions that are 30+ lines of code are often doing multiple things and should be broken into smaller functions to provide a structure that is easy to understand. Instead of copying and pasting code to another location in your program, place the repeated code in a function.

Avoid trivial functions that do too little.

Your main function should be a concise, high-level summary of your program, unless your program is very short.

9. Avoid magic numbers.

If you have a literal numeric value in your code, it often has some meaning. Use a variable or constant to make that meaning clear.

// bad
double bmi = 703.0 * massInLbs / (heightInIn * heightInIn);   // What is 703??

//good
const double ENGLISH_UNITS_CONVERSION_FACTOR = 703.3;
double bmi = ENGLISH_UNITS_CONVERSION_FACTOR * massInLbs / (heightInIn * heightInIn);

10. Use whitespace in a way that enhances readability.
  • Do not use extra whitespace inside brackets and braces:
    • Do this: myFunction(a[2], {1, 2})
    • Not this: myFunction(  a[ 2 ],   {  1,  2})
  • In a function call, do not separate the function name and its argument list by whitespace:
    • Do this: myFunction(1)
    • Not this: myFunction  (1)
  • Use a blank space before and after the = sign, relational operators and logical operators: 
    • i = i+1 
    • i <= j
  • Use a blank line before and after chunks of code that carry out some sub-task.
  • Separate function definitions by a blank line.

11. All #define should be uppercase - multiple words should be separated by underscores.

#define SECONDS_PER_HOUR 3600

That said, there are issues with #define. Consider whether const is a better choice:
const int SECONDS_PER_HOUR 3600

12. Initialize pointers.

When declaring a pointer, always initialize it. If you do not yet have a value for it, then initialize it to NULL. This rule will help you avoid memory errors, which can be difficult to find.

13. Use of the "break" command

Try not to use the break command except for when using the switch. Enter and leave loops in one place. It is much easier to debug this style of code is much easier to debug.

14. Limit the number of return statements in functions

It is much easier to debug code that has a single return at the end of a function. This is not always possible, but try to nhave as few return statements as you can.