|
A function contract provides precise information on what a function accomplishes. It is a statement of the problem that the function solves.
A function contract is not a description of the function body, or of how the function works.
The standards require you to put the contract for a function immediately before the function definition.
The standards for this course require every function to have a clear, precise, well-written contract. You can expect roughly 10-15% of your assignment grades to be related to contracts.
We will see examples of contracts as we go. You have already seen some: the comments that precede example function definitions.
A contract must say exactly what the function accomplishes and how its parameters affect what it accomplishes, and no more. The remaining items are just clarification of this overarching definition of a contract.
For a non-void function, say what the returned value is, relative to the parameters. Use the word return. Do not use "find", "get", "produce", "compute" or any other word as a substitute for return.
Say what one call to the function accomplishes. If the function computes distance between two points A and B, say that. Do not say that it computes all of the distances that the program ever computes.
Write in complete sentences. Use correct spelling, punctuation and grammar. Do not omit the subject of a sentence. "Prints x" is not a sentence. Refer to the function by its name, not as "it" or "function".
Be sure to make it clear how every parameter influences what the function accomplishes. Refer to parameters by their names, not by their types. If a parameter is called x, then refer to it as x, not as "the number" or "the queue" or "it". If you refer to x ten times, refer to it as x ten times. This is not the sports page.
Assume the reader can see the function heading. Do not redundantly provide information that is obvious from the heading unless it is short and makes the contract clearer. Do not duplicate the entire function heading in the contract.
Do not discuss the function body. Do not refer to local variables in the body. If the body contains a loop, do not say so. If the body contains an if-statement, do not say so. You should be able to add more things not to say about the body by consulting the first sentence in this item.
Do not say where this function fits into the program as a whole. The documentation for function f documents f and only f . Do not say which other functions use this function. That is their responsibility.
Do not say where parameters come from. That is not this function's responsibility. If function A reads a number N from the standard input and calls B(N), the documentation for B should not say that its parameter comes from the standard input. Consult the first sentence of this item.
Do not be verbose. Make your contracts concise without sacrificing precision. Do not repeat yourself. Do not write something in a way that is difficult to understand, then write more in an attempt to explain what you meant. Say it in a clear and concise way from the beginning.
Proofread your contracts.
Which comes first, drawing up the blueprints for a building or constructing the building? If you answered "blueprints," go to the head of the class.
Which comes first, defining a problem or working out a solution to the problem? A contract is a clear statement of the problem that a function solves. Here are two observations.
If you understand exactly what a function is intended to accomplish, you should be able to write that down.
If you do not understand exactly what a function is intended to accomplish, you have no business trying to code a (C++) definition of the function.
That is not rocket science. The upshot is:
|
Write a function's contract (and heading) before you write its body.
|
Unfortunately, most inexperienced programmers violate that simple rule. When students bring me their work to look at, there is rarely a hint of a contract anywhere in it. What is more, the student is usually incredulous when I say that contracts should be written before function bodies. They ask, how can I possibly document something until I have written it? I hope those students are never put in charge of the design and construction of a building more complicated than a tool shed.
Alert students realize that a written contract serves as an invaluable tool to keep them on track while writing a function definition. Having a precise (but concise) written description of the problem to be solved reduces mistakes and saves you time.
|