Final-project guidelines
Project design document
The design document you
submit should, like any serious proposal or report, be written in Word
or other document editor, NOT a
plain-text editor like Notepad or your programming editor. It should
have an informative title, your
name, and the date. It should identify the problem you propose
to solve
and state your plan for solving it. You may use the
documentation methods described in section Structure of your program in Problem 12.1, without
including any Perl.
The elements of a design document are these:
- Tell the reader what the practical problem is, in language aimed at an analyst who knows nothing about programming.
Include any samples
of input and output
files that will aid in understanding. When the reader has finished
reading this user description, (s)he will know what the program is
intended to do. Several examples of clear problem statements are
provided in the sample projects.
- Tell the programmer how the program works, in language aimed at a programmer who knows nothing but how to program. A programmer must be able, based on
your description alone, to write the program himself. This cannot hold if you
write in vague terms. PLPTH 750
students should
include pseudocode. But
- Don't refer to specific Perl subroutines in your
programmer's description. This description is not specific to the Perl language.
It should be the same no matter what programming language has been used. Don't use Perl syntax, for example foreach.
- Don't waste the reader's time and attention with
housekeeping details like "The input file is opened for reading."
Assume that the reader knows Perl as well as you do,
and needs to know only how the data transformations, lookups, and other
operations are done.
- Do specify the variable types (scalars, hashes, arrays)
and data structures (arrays of hash references, etc) that you will use
for each step of your solution.
I
will review your design document and may request changes and
resubmission. Do this promptly; do not wait and turn in an updated
document along with your program. On the due date for the program,
submit only the program.
Your program
- Your program should include the elements of the design
document as a leading comment. It should also show the name of the
programmer and the date that this version of the program was released.
- Compose an informative usage message, as we have seen in
lecture and example code
- Check the number of input arguments, as shown in lecture
and example code
- Your main program, after collecting and checking the input
variables, should consist only of calls to subroutines (yours, not
Perl's).
- Write a comment before each subroutine definition that
concisely
explains what the subroutine does -- unless it is simple and obvious
from the subroutine name.
- Any statement or other operation that might cost a reader
some
thinking to figure out should be commented for ease of understanding.
This is especially recommended when you have mentioned this operation
in the programmer's description. The reader can now see what you were
referring to.
- Do not use literal values anywhere but in constant
definitions at the top of your program. Use a special naming convention
for any such constants: good ones are $ALL_CAPS or $sUsage_str and $kNumerical_constant. (Bitter experience has shown that there
exist students who will obediently name a variable $kNumerical_constant. Don't do this, as your instructor will
become severely agitated and possibly suicidal. This name is shown only
to illustrate the format of your constant: it begins with a lower-case k so that it looks different from the names
you assign to variables. In fact, the name must reflect its role in
your program. Examples: $kID_column,
$kCodon_length).
Assign
the value to a constant only in that definition, and nowhere else in
your program.
- For the previous requirement, use common sense. If your
documentation has said that you must double or halve a quantity, using
the literal value 2 is fine; don't define constant $kHalf. Likewise, it's
sometimes necessary to use the value 1. If you don't yet understand the
difference between a variable that could
take another value in a different context and one that couldn't
meaningfully do so, you're in the wrong course.
- Except for named constants (see preceding two guidelines), do
not use global variables inside subroutines, and avoid doing
even that
if you can.
- Pay attention to your indenting, both in pseudocode and in
code. Place subroutines after the main code, with a blank line
separating them. (I even like to insert a separator such as ##### Subroutines
#####).
|