Descriptive names must describe the correct thing [4 points each, 3% max]
|
You are encouraged to use descriptive names, as long
as they do not become so long that they are unwieldy.
A descriptive name must make sense. If something is a horse, do not call it kangaroo. If something is an edge, do not call it vertex. The maximum size of an array of edges must not be called MaxNumVertices. |
|
If a program does something that is not obvious, such as
storing a particular value in a strange location or storing
the size of an array inside the array, that behavior must be very
clearly documented.
Better yet, avoid trickery altogether. Undocumented trickery is lethal to large pieces of software. It creates errors that are very difficult to find. |
Every function must have a contract [3-8 points each, 16% max]
|
There must be a clear contract for every function
that satisfies the
requirements for contracts.
You will lose 3 points for a contract with small problems, 6 points for a contract that is very poor, 8 points for a contract that is missing or that is an outright lie. The remaining items indicate particulars of contracts. They are not graded separately. Each issue is either minor (3 points), major (6 points) or lie (8 points). A contract with up to 3 minor errors and no major errors loses 3 points. A contract with up to 2 major errors loses 6 points. A contract with 3 or more major errors loses 8 points. |
The contract should tell the truth about what the function does. [lie]
| This means your contract is false. It says something that is not what the function really does. Don't do that. |
A contract is not supposed to tell how a function works. [major]
|
This means your contract tries to tell how the function works, or talks about
local variables within the body of the function. A contract is supposed
to tell what a function accomplishes. It must talk about the function's parameters,
but not anything that is hidden in the body.
This is considered minor if the how-information is accompanied by a clear explanation of what the function accomplishes. |
A contract must explain how each parameter affects what the function accomplishes. [major]
|
This means your contract does not explain how the parameters affect what the
function does. You will also get this if you describe some of the parameters, but
omit some. The contract must describe all of the parameters.
Note that it is not enough just to mention that the parameters exist. That provides no information, since it is obvious from the function heading. The contract must explain how the parameters affect what the function does. |
A contract must refer to parameters by name, not by pronouns such as "it" or by pronoun phrases such as "the integer" or "the graph". [minor/major]
| This means you are talking about parameters using pronouns or pronoun phrases. Use their names. If it is impossible to understand which parameters are being referred to, this becomes a major item. |
A contract should describe a parameter in terms of how it affects what the function accomplishes, not in terms of where it comes from or how some other function chooses a value for the parameter. [minor]
|
This means that, instead of telling what this
function accomplishes in terms of its parameters,
you are telling what purpose some other function uses this function for,
or are telling how another
chooses the values to pass for parameters.
Do not say how this function fits into the overall program. The documentation for function f should describe f, not some other function. |
If a function returns a non-void value, the contract must explain what the returned value means. [major]
| This means that you have not explained what the returned value means. It is not adequate just to say that the function returns an integer. What is the significance of the returned value? What information does it provide to the caller? |
If a function has requirements concerning its parameters, state them. There should be no undocumented requirements. [minor]
| This means that you have not documented critical requirements that the caller needs to know. |
If a function has side-effects that are important to the caller, document them. [major]
| This means that you have not mentioned side-effects that the function performs. For example, if a function writes something to the standard output (excluding trace prints), say so in the contract. If the function changes the value of a call-by-reference or call-by-pointer parameter, say so. |
| The contract is difficult to understand or is no more than a hint. |
Use complete sentences, correct spelling and correct punctuation. [minor/major]
| This means that you have not written your contract using standard English conventions. If the errors are extensive and intrusive, this is a major item. |
The contract is irrelevant or describes a different function [major]
| This means that your contract describes something other than this function. |
| This means that you have omitted the contract altogether. |
Describe each .cpp file in a comment near its top. [3-6 points, 2% max]
|
Each .cpp file must have a comment near its top that describes (1) what the module does or
what its purpose is,
(2) how to run the program (if there is a main function in the module),
and (3) input format, if there is input. The comment should also
show a sample of what the program writes on a particular input.
Header files (.h files) do not require such a comment. If the module contains a main function, this comment serves as a contract for the main function. If the module does not contain a main function, the comment tells what the module provides and lists the components of the interface. |
| Choose sensible type names. If a type is used to describe a vertex, call it vertex, not graph. If a type describes one edge, call it edge, not edges. |
Every type definition must have a description [3-8 points, 5% max]
| There must be a clear description for every type, with the exception of a type that is defined just to be a pointer to another type. The description must tell what an object of the type represents. For a structure type, each individual variable must also be described, telling what property of an object it represents. You will lose 3 points for a minor problem, 6 for a major problem and 8 for no attempt to document a type. |
Field names of structure types must be descriptive. [2 points each, 1% max]
| Avoid single-letter names for fields of structures. Choose sensible, descriptive names. |
Do not use l, o or O for variable or names [1 point per variable or parameter, 1% max]
| Names l (lower case ell), o (lower case o) and O (upper case O) tend to be confusing. It is easy, for example, to confuse l with 1. Do not use those names. You may use L. |
|
Choose a name for a function that suggests what the function does.
Do not choose unnecessarily long function names, but make the
names sensible.
Do not choose a misleading name. A function that removes something should not be called insert. A function that prints a tree should not be called showlist. If a function does not create an edge, do not call it createEdge. Use common sense. Avoid function names that are so vague that they do not really describe anything. For example, a function called createArray presumably creates an array. That is fine if all it does is create an array. But that is not very useful if what it really does is create and initialize an array for a specific purpose. It is better to choose a name that is descriptive of the purpose. |