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. |
| There must be a clear contract for every function that satisfies the requirements for contracts. The items below are used for explaining specific issues with contracts. |
| [NO-CONTRACT] means that you have omitted the contract altogether. |
The contract should tell the truth about what the function does. [CONTRACT-INCORRECT]
| [CONTRACT-INCORRECT] means your contract lies. It says something that is not what the function really does. |
A contract tells what a function accomplishes, not how it works. [CONTRACT-HOW]
| [CONTRACT-HOW] 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]
|
[CONTRACT-PARAMETERS] 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]
| [CONTRACT-PARAMETER-NAMES] 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]
| [CONTRACT-CONTEXTUAL] 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]
| [CONTRACT-RETURN] 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]
| [CONTRACT-REQUIREMENT] 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]
| [CONTRACT-SIDE-EFFECT] 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. |
| [CONTRACT-VAGUE] The contract is difficult to understand or is no more than a hint. |
Use complete sentences and correct punctuation. [CONTRACT-ENGLISH]
| [CONTRACT-ENGLISH] means that you have not written your contract using standard English conventions. |
The contract is irrelevant or describes a different function [CONTRACT-IRRELEVANT]
| [CONTRACT-IRRELEVANT] means that your contract describes something other than this function. |