CS 1321 (Principles of Algorithm Design II):
Guidelines for Programming Assignments

What to turn in

Your program's source code, submitted electronically, as described below. The program must begin with the following:
- Comments giving your name and the assignment number.
- Comments describing what the program does. You don't have to describe the "how" here, just the "what" -- i.e., the input and output.
- Comments documenting any choices or assumptions you made in writing the program. For example, if input is a sequence of numbers, and you assume there will never be more than 100, you should mention this assumption in the opening comments.
(Optional) On paper, a "story page" describing any difficulties you encountered in doing this assignment and what you did to resolve them (if anything -- you can also use this "page" to describe difficulties you were unable to resolve).

Tips:

Be sure your name and the assignment number appear on everything you turn in.
Always try to turn in something, even if it's not completely correct or complete. Partial credit will be given when appropriate.

Submitting programs electronically

To submit your program, e-mail its source code (as described below) to the address corresponding to your section number. You will be told, for each assignment, what source file or files are to be submitted.

cs1321-3@cs.trinity.edu for the 10:30 section.
cs1321-4@cs.trinity.edu for the 11:30 section.

(Please use this address only for submitting homework. If you have questions, please use my main e-mail address bmassing@cs.trinity.edu.)

To e-mail source code, use one of the following approaches. You will get an automated reply indicating that the mail was received; if you do not get such a reply within a few minutes, this could be an indication that you've done something wrong.

From Linux/Unix, type the following command:
shar -m sourcefiles | mail -s "the subject" cs1321-n@cs.trinity.edu
where
- sourcefiles is a list of files containing your source code (names separated by spaces).
- the subject is the subject header requested for the assignment (e.g., "cs1321 homework 1").
- n is your section number.
(What this does is use the shar program to combine your sourcefiles into a single file and then pass that to the mail program, which mails it to the cs1321-n account.)
Normal output of this combination of commands is a line for each of your sourcefiles, for example:
```
        Saving yourpgm.cc (text)
	
```
If you see radically different output -- e.g., the whole source of your program(s) scrolling by -- you have probably done something wrong; check that you typed the command as described, include the | (vertical bar) character.
If all goes well, you should get an automated e-mail reply indicating that the mail was received. If you mistype the e-mail address, you should get a reply back from the mail system telling you about the problem. Either way, the reply will be sent to you at the machine where you submitted the homework. See Reading and forwarding mail under Unix for instructions on how to read it or forward it.
Using any mail program that supports attachments, send a message to the appropriate address (described above), with a subject header as specified for the assignment, and attach the file(s) containing the source code (i.e., send each source file as an attachment). The result should be a single mail message with one or more attachments, one for each source code file.
If all goes well, you should get an automated e-mail reply that the mail was received. If you mistype the e-mail address, you should get a reply back from the mail system telling you about the problem.

If for some reason you submit a homework and then want to submit it again (perhaps you found a mistake in your program after submitting it), just repeat the above procedure. I will grade the most recent version I receive.

Grading criteria

Program correctness. This will be evaluated by executing your code using a standard set of inputs.
Clarity of source code. See the following section for suggestions on how to write clear code.
Documentation -- header comments describing what the program does, usually in terms of its inputs and outputs. See the following section for suggestions on how to write good documentation.

Tips for writing good documentation and "clear code"

Something that early programmers did not fully appreciate is that programs tend to take on a life of their own, being reused and modified over a period of years, often by people other than their original authors. The better a job the original author did of documenting the program and writing it clearly, the easier it will be to reuse and modify. The sample programs are examples of what I consider reasonable documentation and clear code.

Documentation

By "documentation" I mean comments at the start of the program that help potential users understand exactly what the program does without necessarily understanding how, and definitely without reading the whole program. Generally speaking, these comments should describe the program's inputs (command-line arguments, file input, input from the keyboard, a keyboard) and outputs (file output, output to the screen) and how they are related. See the sample programs for examples.

Clear code

The object of these suggestions is to make the code clear and readable for the human reader, perhaps a programmer who wants to reuse it with modifications. Here are some tips for writing clear code.

If a variable's purpose is not obvious from its name, add to its a declaration a short comment describing its intended meaning and usage. This can also be a help in thinking about how to write the program in the first place. Note that C++ allows you to put the comment on the same line with the declaration.
Choose a consistent indentation style for loops and conditional constructs (if / else). That is, indent the statements that make up the body of a loop, and indent the statements to be executed as part of an if or an else. This makes the control flow of the program stand out better.
If there is something tricky about the program -- something you think will confuse the reader -- include a comment or a block of comments to explain what's going on.
If the program is long, use comments to mark it off into sections and indicate the overall purpose of each section.
But don't include comments just to have comments! For example, the comment
//declare the variables
is useful only in example programs for beginners; after your first few programs you shouldn't need such a comment. Also, comments that just echo what the code is doing -- for example,
count++; // increment count
-- are not helpful (again except in example programs for beginners).
If your program contains more than one function, include for each function comments that describe its purpose, parameters, and return value. You may put these comments before the function's prototype or before its definition.