Describe what a program does in a comment near its top. [TOP-COMMENT: 1-2 points]
| Write a descriptive comment telling the program's purpose and what the program does when you run it. |
| There must be a clear contract for every method 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 method does. [CONTRACT-INCORRECT]
| [CONTRACT-INCORRECT] means your contract lies. It says something that is not what the method really does. |
A contract tells what a method accomplishes, not how it works. [CONTRACT-HOW]
| [CONTRACT-HOW] means your contract tries to tell how the method works, or talks about local variables within the body of the method. A contract is supposed to tell what a method accomplishes. It must talk about the method's parameters, but not anything that is hidden in the body. |
A contract must explain how each parameter affects what the method accomplishes. [CONTRACT-PARAMETERS]
|
[CONTRACT-PARAMETERS] means your contract does not explain how the parameters affect what the
method 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 method 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 method accomplishes, not in terms of how some other method chooses a value for it. [CONTRACT-CONTEXTUAL]
| [CONTRACT-CONTEXTUAL] means that, instead of telling what this method accomplishes in terms of its parameters, you are telling the specific purpose that some other method uses this one for, or are telling how another chooses the values to pass for parameters, or where those parameters come from. |
If a method 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 method returns an integer. What is the significance of the returned value? What information does it provide to the caller? |
If a method 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 method 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 method performs. For example, if a method writes something to the standard output (excluding trace prints), say so in the contract. If a method changes an object, say so. |
| [CONTRACT-VAGUE] The contract is difficult to understand or is no more than a hint. |
| [CONTRACT-VERBOSE] The contract is much too wordy. Do not talk about irrelevant things, or things that are obvious from the method heading. For example, if there is an integer parameter called n, do not say "This method takes an integer parameter called n." A person reading the contract can see the method heading. |
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 method [CONTRACT-IRRELEVANT]
| [CONTRACT-IRRELEVANT] means that your contract describes something other than this method. |