Correctness is an important criterion, but does not guarantee a top mark. Grades on programs will be based on:
Documentation for any program falls into two categories: internal and external. Internal documentation consists of the comments included in the program. They generally fall in three places: at the heads of procedures, at declarations, and at particularly tricky or opaque segments of code. Procedure-head comments describe the effects of the procedure and assumptions about its inputs and outputs. The procedure name should convey as much of this information as possible. Names of variables, types, constants, and field selectors should also be as meaningful as possible, with a comment next to the declaration to fill in extra information. Comments should be written before the rest of the program.
External documentation (which you may include as a long comment right at the beginning of the program itself) has two types: for the typical user, and for someone who wants to understand how the program works. The first kind of documentation includes details of how to call the program, its options, formats of data, limitations, bugs, and special features. For course programs, part of this information is included in the assignment and need not be repeated. Emphasize both the negative aspects of your program (limitations, known bugs) and the positive aspects (extensions, special features). If you do not include the former, we will assume you didn't realize the limitations were there. If you do not include the latter, you may not get credit for special features.
There are a few general programming standards that you are expected to follow in this course.
http://cs.wpi.edu/Help/documentation-standard.html
.
/* * <filename> -- <brief title and/or purpose> * * programmer -- <you> * * date -- <creation date> * * modification history * * <date> <change made> */
/* * <name> -- <brief statement of action performed in terms of input * and output parameters along with the value returned.> */
#define
to define any constant (numeric, character and
string) that has meaning apart from its literal value. Most numbers other
than 0 or 1 fit into this category.
if (i == 0) { bDone = TRUE; j++; }
if (bCheck) { ... } else if (i > 0) { ... } else { ... }
This section describes conventions for creating procedure and variable names. These conventions will be used in examples given in class. You are strongly encouraged to follow these in your coding.
Where possible, name procedures by the (single) action they perform. In most cases, the name should be a verb or verb phrase. Capitalize words that appear in the name (for example, ReadPoly()).
Variable names should be mnemonic. That is, the name of the variable should relate to some property of the values that variable can contain. Thus variables will generally have a type and when necessary a qualifier if there are many variables of the same type.
The naming convention provides type construction rules or schemas that show how to construct compound types from simple types. A large program typically has only a few simple types. This ability to quickly and easily construct names of variables based on the types they contain is the real power of the convention.
Let X and Y denote arbitrary tags. Each of the following schemas shows how to construct a new type from the given simple type.
Note: This convention is often referred to as ``Hungarian'' after the heritage of its designer, Charles Simonyi. These conventions were summarized from a document by John T. Korb from Purdue University. More details are available for those that are interested.