CS167 C Programming

Guidelines for submitting a programming assignment

Submitting your programming assignment

You need to do the following things in order to get full credit for your assignment, assuming that it works to your satisfaction:

1. Run the program to produce a sample output. You will have tested your program on many forms of input, but this run is just to show off its capabilities. There are many ways to do this, but for programs that only write to standard output, and read from standard input, the best way is to use UNIX (or DOS) redirection:
   
   airplane% a.out < infile > outfile
2. This will produce the output in the file called `outfile' which can then be printed with:
   
   airplane% lpr outfile

Although the lab. has many printers, please use lpr for this purpose as it costs about one tenth of the laser printer cost.
3. Hand in your listing (source code plus sample output) to me either in class, in the main CS office, or in my mailbox.
4. Finally, e-mail the source code (only) to the grader:
   
   airplane% mail hhuang < myfile
   airplane%
   
   where myfile is the name (with extension .c) of your source code file.

Layout and documentation

Presentation of programs is a vital part of the programming endeavor. In a wider world your program will be read by other programming colleagues, managers, non-programmers, and yourself. In order to help the reader, two aspects of presentation must be considered:

1. Layout of the source code.
2. Program documentation.

Layout can be split into:

1. File layout. A C program consists of multiple files, each of which has multiple declarations and/or definitions. In each file, declarations should come before definitions. Thus the order should be #includes, function declarations (prototypes), global variable declarations with extern, global variable definitions, function definitions.
2. Function layout. The order here is the function header, then local variable definitions, then the function body in the form of statements. The braces surrounding the body should either be in column 1, or the left brace can follow the function header. Statements may be grouped according to the task being performed by separating them with blank lines. Each statement or embedded statement should be indented from the previous line.
3. Statement layout. If the statement has a compound statement embedded in it, its braces should follow the convention used for the function body, i.e. either the right brace is directly below the left brace, or the left brace follows the statement introduction, and the right brace is directly below the first letter of the statement keyword. Always surround operators by spaces, and separate keywords from other code with a space.

Documentation consists of comments. These are of three sorts:

1. File level. A header comment is necessary for every file. This must contain your name, class number and section, the date of submission, and the assignment number. Other things to include might be a brief description of the whole project, the compiler used, and other special circumstances.
2. Function level. Every function, however small, should have a comment block stating, at least, its purpose. The comment can precede the function or occur immediately after the header. Optionally it can contain a description of the algorithmic method used , a description of its parameters, what values the function can expect, and a list of functions that call it.
3. Statement level. Sometimes it is appropriate to add a comment to a statement or group of statements to clarify a method or technique used, or to indicate typing or other information on the values involved.

Here is a minimal example program showing all the points mentioned above.

/* this file level comment block contains the file header:
   name, class, section, assignment no. etc.
*/

#include <stdio.h>

extern int globalDefinedElsewhere;
void functionDefinedElsewhere(int x);

int globalDefinedHere;

int functionDefinedHere(int x) {
/* this function level comment describes the purpose of the function,
   and perhaps the values of the parameters expected */


   /* this section tests x for a zero value and calls
      a function if it is not */
   if (x == 0)
      printf("x is zero\n");
   else {
      /* this statement comment might say where this
         function is defined */
      functionDefinedElsewhere(x); /*a comment might be here */
      printf("Called function\n);
   }

   /* this section indicates that the function has completed
      successfully */
   printf("Finished function");
}