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, use the automated assignment submitter to send the source code to my account.

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, and function declarations and /or definitions.
  2. Function layout. The order here is the function header, then the function body in the form of statements. Local variable definitions must precede any executable code in the body. 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. Module 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. Functions, optionally 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: for C; for C++.