CS 1320 (Principles of Algorithm Design I):
Guidelines for Programming Assignments
What to turn in
- A printed listing of your program source code.
This listing should include, at the start:
- 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.
- If the program uses input data, the input data you used to test
the program. You should try to choose "good" test input --
input for which it is easy to see whether the answers are
correct but that explores all of your program's possible
behaviors.
- A listing of your program's output when run with the test
input data.
- (Optional) A "story page" describing any difficulties you
encountered in doing this assignment and what you did to
resolve them.
Be sure your name and the assignment number appear on
everything you turn in.
Grading criteria
- Program correctness -- does the program do what it's
supposed to?
- Thoroughness of test data.
- 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.
As an example of the distinction between what and how,
notice that the documentation for the
sample program quadratic
describes only the input (sets of coefficients for quadratic
equations) and output (roots of the corresponding equations)
without explaining how these roots are computed.
If we later
found a better method of computing the roots, we could replace some
of the body of the program without altering the documentation.
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, include
a comment or a block of comments to explain what's
going on.
For example, in the sample program
quadratic,
a comment explains the use of the read-input statement
as the condition of a while loop.
- 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.
- 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.