CSCI 235.052 Programming Guide Fall, 2002
Professor Szenher
Following directions
To some extent, programming is an exercise in
following directions. The specifications for a program may come from an
instructor or an employer or you may need to generate some of them yourself.
The specifications describe the input, what the program is to do with it, and
the output. Make certain that you understand exactly what is required before
you start to code, and make certain that you deliver it. Specifications
should also set standards for how the program should be written: documentation,
modularity, user-friendliness, programmer friendliness, and no-run conditions.
Your assignments will insist on those as well.
The following sequence should help you manage the
task and provide proof that your code functions correctly.
• For each module (function or class), write a small
program (a driver) with print diagnostics to test every aspect of
the module. For example, if you use a class to implement a linked list, write a
program that creates an empty list, and then prints it. Next your driver should
place several items on the list, and print the list after each insertion. Then
your driver should search for several items on the list (some present, some
not) and print the results and the list itself after each item. Finally your
driver should delete several items from the list, and print the list after each
deletion. Examine the printout carefully. Once you are satisfied that
the module is working correctly, archive the driver. Do not submit it.
• Design an input file format and create data for it.
Do not write code that requires input from the keyboard while running. All
directions should be embedded in the program or in a file that the program
reads. In the latter case, print out and submit the direction file as part of
the assignment.
• Write a small (no more than 5 lines) main program.
Each line should call a subroutine. For now, none of these subroutines exist,
so they are called stubs. Initially write a dummy routine for each stub
that prints a message, such as “arrived at stub for input.” Here is an example:
routine foo
read_in_foo_data
compute_for_foo
output_for_foo
• In the order of their appearance in the main
program, replace each stub with a set of one or more correct routines of no
more than 30 lines each; use stubs in these too where necessary. Check
carefully that your routines meet the program specifications, i.e., follow
directions. To make certain that a routine is correct, insert print
diagnostics as you did with the drivers. For example, “I just built the stack
and it contains” followed by a list of its contents. Once you are satisfied
that a routine is working correctly, eliminate its print diagnostics and move
on to the next routine.
• Design an output format that fits the
specifications and looks good on paper. A comparison table matches two or more
sets of data against each other. Write
output routines to produce your output in that format.
• If templates are new to you, write the code for the
data structure once to run on some simple variety of data, such as integers.
Then go back and make it a template, and write a driver to test it on several
kinds of data.
• Test your program on a small amount of data
first. Look carefully at your output. Does it make sense? is it what you
expected? Beware of zeros, negative numbers, misplaced decimal points, hex-like
garbage, and so on.
• Once you are satisfied that it is correct, run your
program on the full data set according to the specifications.
• Document, document, document. Proofread and spell
check.
• Crosscheck your work against the programming
standards below.
In the event that you do not have time to finish a
program, you must have functioning code to show. Assuming that you have
followed the directions above, you should be able to provide modules with
drivers and show the drivers working. Also provide routines with print
diagnostics still in them, and show what you were able to accomplish. Abide
by the programming standard in any case. If none of your code produces
output, you will receive no credit.
Programs must be written in C++ on an approved
compiler. Each project must be accompanied by a typed program
analysis statement (PAS) analyzing the results and issues specified in
the assignment. Output must be generated by your program, even if it is
reproduced in the PAS.
Submit each project in the following order:
1. Program cover sheet
2. PAS
3. Design (stubbed program and/or ADTs)
4. Output (ordinary and extra credit, see below)
5. Input (if relevant)
6. Program source code (main program, then header and
implementation files). If you use an STL, submit copies of all code employed. Label
each submitted file with the file name at the top.
You will be graded on the quality of your project. It
is not enough to write a program that runs. A working, correct program only
earns a 70. To do better than that you must meet all of the following criteria,
as reflected on the program cover sheet.
Validity 70%: The program produces correct results, uses appropriate data structures
and algorithms, and fulfills the program specifications precisely.
Documentation 5%: If your program is correct, but I can’t easily figure out what you’re
doing or why it works, there is a serious documentation problem. Comments
should be in clear, grammatical English.
• Begin
the listing with comments that identify the author, the programming language
and compiler, the machine it runs on, and the date written. These are the introductory
comments.
• Describe the purpose and restrictions in the
opening comments of each routine. Specify each routine’s input (preconditions),
output (postconditions), and how to use it, along with any assumptions about
the type of data expected (preconditions), and a brief description of the major
algorithms, data structures, and key variables. These are individual routine
comments.
• Document
completely, including at least one comment for every 5 lines of code.
Modularity 10%: Modularization makes code reusable and easy to debug.
• Each module interacts minimally with a small number
of other modules, and has a clearly stated interface description
(preconditions, postconditions and purpose), including parameters and
non-local variables.
• Each
module receives input via parameters or (in rare cases) external or global
variables; you must justify use of global variables.
• Each
module sends output via a function return or changes in parameter values. Avoid
changing the value of non-local (i.e. global) variables.
• Functions
are organized into small routines (no more than 30 lines is a good guideline).
• Any
number in an assignment should be easy to change (e.g., number of runs, size of
hash table) through use of global constants or function parameters.
User-friendliness 5%: Someone should be reading your output for
information, and it is your job to make it easy for him or her to understand
the results. Therefore:
• Output
should be neat and in a user-friendly format.
• Output
should be in clear, grammatical English.
• Error
messages should be clear.
• Your
program should be robust (test for bad data, always runs to legitimate
completion, never “bombs out”).
• Your
output should demonstrate adequate testing, so the user knows what to expect.
No-run conditions 5%: In your PAS, note the circumstances under which the program will
not function correctly, e.g., input not in English, more than 10,000 data
items, etc.
Programming style 5%: Good programming style facilitates code reuse and
revision, by you or by another programmer.
• Your
program should use meaningful variable names.
• Your
code should prefer clarity to clever efficiency.
• Your
code should have a consistent style throughout, e.g., implement all trees the
same way.
• Your
main program should be brief, clear, and clean. For example:
procedure (main){no main program
should ever be much longer than this}
call
input
call
process
call
output
end main
• Use
blank lines and indentation to show logic and promote readability.
Extra credit: Extensions to the assigned task are sometimes offered. You must complete the assigned task first,
before undertaking any extra credit.
Extra credit is available only for well-executed extensions of
running programs. You must document the extra credit features in the PAS and
clearly indicate the relevant source code (with appropriate documentation and
comments). The extra credit features must also be clearly demonstrated in the
printed output after the required output.
LATENESS:
Programs are due at the end of class on the date specified by the instructor. No
late programs will be accepted. You will need a program to answer a
proportion of the quiz questions.
Academic Dishonesty: Discussion of assignments is fine, but you must write
your own programs. You may use code from the text, the text’s website,
or an STL, but you must document that at the beginning of the program analysis
statement and include the full URL in your PAS. Giving and receiving
programs or problem solutions are equally reprehensible.