CS2023 C Language Coding Standard

It is a requirement of CS2023 that the following guidelines be observed for all coding assignments.

Source File Organization

The ordering presented here should be used.
Not all of the section types will necessarily be used in all programs, in which case don't put them in.
Each of the sections should be clearly identified within the program source file using comments and blank lines.

File Documentation: the Doxygen documentation system must be used for all comments; instructions are given in the CS2023 User's Guide. The first item in a source file must be a Doxygen comment block giving the author, date, and a brief description of what functionality the code provides (using the @brief, @author, and @date commands), followed by a more detailed description, if needed. For example:
```
 /** @file       
  * @brief krfind: print lines that match pattern from first argument    
  * in file given by second argument.     
  *   
  * Based on Kernighan & Ritchie, The C Programming Language,   
  * 2nd edition, p. 116.      
  * @author Eric Aubanel      
  * @date October 4, 2002     */
```

Note that the brief and detailed descriptions must be separated by an empty line (containing only a "*").

Each individual function within the file must also have a Doxygen comment describing the functionality it provides and documenting its parameters and return value (using the @param and @return commands). For example:

/** @brief getline: get line from file (file handle inFile)       
 *  @param  line The buffer where the line will be stored      
 *  @param  max The size of the buffer     
 *  @return The number of characters read   */

A detailed description and other comments (bugs, etc..) may also be included (see Doxygen documentation).

Preprocessor Information: list the header files that are needed, followed by the preprocessor macros. Preprocessor macro names should use capital letters only.
Type definitions: programmer-defined data types, using the C keyword typedef.
Function Prototypes: prototypes for all programmer-defined functions should be presented. The arguments should be specified with both data type and name (e.g. float xvalue).
Main Function: the main program body.
Functions: functions should be listed last. Ordering of the functions themselves is at the discretion of the programmer, however a top-down approach is suggested. This means that the first functions defined should be those that are called from the main program and that functions calling no other function are listed last.

Function Format The main function must be of type int and must

return appropriate return codes. Functions must have meaningful names, leaving little question about the purpose they serve within the program. Functions should have at least the following three sections:

Variable Declaration: all variables to be used in the function will be listed immediately following the function's opening brace. Comments are only required for global variables (which should normally not be used, except in specific cicumstances), constant definitions, fields in structures. When commenting variables, use Doxygen single-line format (/**< comment here */). Instead of commenting each variable, use meaningful names. Names made up of multiple words should either have the initial letter capitalized, except for the first word (e.g. frontOfTheQueue), or be separated with underline characters (e.g. front_of_the_queue).
Function Code
Function return: if the function returns a (that is, does not have type void), in general the return statement should appear as the last statement of the function.

Indentation

Each block or level of scope should be set off by indenting using two to four spaces (choose a value and stick to it). In the Emacs C mode this will be done automatically, which also helps spot syntax errors as you write. Statements that exceed 72 characters wide should be broken into more than one line so that the continuation line is indented from the parent line. Example:

int log2(int n){
  int current=n;
  int count=0;
  int useless=n;
  while(current>0){
    current /= 2;
    count++;
    if (useless){
      useless = current/current+useless*count+3*count+useless*current
                   +2*useless;          
    }
  }
  return count;
}

The use of side effects

The use of expressions with side effects (except for some idiomatic cases we will discuss in class) is discouraged since it distracts from readability and comprehension.

The gets() Library Function

Use of the standard i/o function gets() is absolutely prohibited since introduces an an unavoidable security hole and/or bug into every program it is a part of.