Describe each .cpp file in a comment near its top. [Top-comment: 1-2 points]
| Each .cpp file must have a comment near its top that describes what it is for. If the module contains a main function, the comment serves as a contract for the main function. If the module does not contain a main function, the comment tells the purpose of the module. |
|
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, it must be very
clearly documented.
Better yet, avoid trickery altoghether. Undocumented trickery is lethal to large pieces of software. It often creates errors that are very difficult to find. |
Every type definition must have a description [Type description: 1-5 points]
| 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. |
|
There must be a clear contract for every function
that satisfies the
requirements for contracts.
You will lose 1 point for a contract with small problems, 2 points for a contract that is very poor or is missing and 3 points for a contract that is an outright lie. |
| This means that you have omitted the contract altogether. |
The contract should tell the truth about what the function does. [Contract incorrect]
| This means your contract is false. It says something that is not what the function really does. |
A contract tells what a function accomplishes, not how it works. [Contract how]
| 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. |
A contract must explain how each parameter affects what the function accomplishes. [Contract parameters]
|
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. 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". [Contract parameter names]
| This means you are talking about parameters using pronouns or pronoun phrases. Use their names. |
A contract should describe a parameter in terms of how it affects what the function accomplishes, not in terms of how some other function chooses a value for it. [Contract contextual]
| This means that, instead of telling what this function accomplishes in terms of its parameters, you are telling the specific purpose that some other function uses this one for, or are telling how another chooses the values to pass for parameters, or where those parameters come from. |
If a function returns a non-void value, the contract must explain what the returned value means. [Contract return]
| 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. [Contract-requirements]
| 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. [Contract side effect]
| 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 it 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 and correct punctuation. [Contract english]
| This means that you have not written your contract using standard English conventions. |
The contract is irrelevant or describes a different function [Contract irrelevant]
| This means that your contract describes something other than this function. |