C Programming Style Guide

Getting the computer to understand your program is no guarantee that people will be able to follow it. Just as you would edit an English composition, you should spend time revising a computer program to make it elegant and readable. The following guidelines will help you write programs that are easy to read and modify. The grader may expect your assignments to conform to these style and documentation conventions.

• Include a header comment at the top of the file. This header should contain:
  1. Your name (and the names of any people you work with)

  2. The course number (e.g., CPSC 211) and your section number (e.g., 201-203)

  3. The name of the programming assignment (e.g., Program 1)

  4. The date of last modification to the file.
  5. Under the heading "PURPOSE", describe the purpose of the code in that file. Be brief and informative. Communicate your approach to solving the problem.

  6. Under the heading "ASSUMPTIONS", state assumptions you make regarding the problem to be solved, the kinds of inputs your program will accept, and deviations from the assignment requirements (note that any significant deviations should be cleared with the instructor in advance.) This header must include:
     • any assumptions made about the input
     • limitations of the program with regard to the requirements
     • known bugs
     Specific assumptions regarding particular functions may be expressed in header blocks above the relevant functions.

• Include a brief header block comment at the top of each function and typedef. The format is shown below:

  /*******************************************************************
  *  The function/typedef name
  *
  * Description of the function/typedef purpose
  *******************************************************************/
  

• Use inline comments sparingly but whenever necessary. Use inline comments whenever the meaning of the code is not immediately obvious from the text. For example, inline comments can be useful to summarize cases in a conditional expression as follows:

    
     if (xPosition < xLeft)               /* left of box */
        ...
     else if (xPosition > xLeft + width)  /* right of box */
        ...
     else if (yPosition < yBottom)        /* below box */
        ...
     else                                 /* inside or above box */
        ...
  

• Write self-documenting code.
  1. Choose meaningful names for all variables, parameters, and functions. Use complete words instead of abbreviations where practical.

  2. Use named constants instead of sprinkling numbers throughout your code. Rule of thumb: if a constant is used more than once, give it a name.

  3. Avoid repetitious code by writing an appropriately named function and calling it multiple times.

• Follow standard formatting conventions.
  • Capitalization:

    variables and function names

    the first letter is lower case, with the first letter of each subsequent word capitalized
    for example, int caloriesFromFat = 18;

    constants

    the entire word is capitalized
    for example, const PI = 3.14159;

  • Indentation:

    braces

    the open brace ({) goes at the end of the line before the start of the code block.
    the close brace (}) goes on its own line, indented to match the beginning of the line containing the corresponding open brace, and include a descriptor on the closing brace line that indicates which opening brace it matches

    code inside braces

    indent one level (about 3 spaces) for each level of curly braces ({})

    code inside conditional statements and loops

    indent one level for lines of code in conditional statements and loops

    continued lines

    when a statement continues across two or more lines, indent the second and remaining lines an equal amount past the start of the first line of the statement.

    Example of proper indentation technique:
    

       int withdraw (int requestedAmount) {
       if (balance < requestedAmount) {              
          return 0;                                
       }                                                /* end if */
       else {
          balance = balance - requested amount;
          printf("Withdrawal of $" %4.2f
                             successful, leaving %4.2f.",
                             requestedAmount, balance);             
          return 1;
       }                                                /* end else */ 
    }                                                   /* end function */
    

• Use common sense. Remember that this style guide is only a guide. Your primary concern should be making sure that others can read and understand the text of your program. If you think an additional comment or particular organization will get your ideas across more effectively, do it. However, if you are considering deviating significantly from the guidelines or if you are in doubt about something, please discuss it with us first.

This style guide was adapted by Jenny Walter and Jennifer Welch from one prepared by Prof. Ken Goldman at Washington University at St. Louis.