# Abstraction and Specification * * * <i> Topics: * specifications * abstraction by specification * specification of functions * comments </i> * * * ## Specification A *specification* is a contract between a *client* of some unit of code and the *implementer* of that code. The most common place we find specifications is as comments in the interface (`.mli`) files for a module. There, the implementer of the module spells out what the client may and may not assume about the module's behavior. This contract makes it clear who to blame if something goes wrong: Did the client misuse the module? Or did the implementer fail to deliver the promised functionality? Specifications usually involve preconditions and postconditions. The preconditions inform what the client must guarantee about inputs they pass in, and what the implementer may assume about those inputs. The postconditions inform what they client may assume about outputs they receive, and what the implementer must guarantee about those outputs. An implementation *satisfies* a specification if it provides the behavior described by the specification. There may be many possible implementations of a given specification that are feasible. The client may not assume anything about which of those implementations is actually provided. The implementer, on the other hand, gets to provide one of their choice. Good specifications have to balance two conflicting goals; they must be * **sufficiently restrictive**, ruling out implementations that would be useless to clients, as well as * **sufficiently general**, not ruling out implementations that would be useful to clients. Some common mistakes include not stating enough in preconditions, failing to identify when exceptions will be thrown, failing to specify behavior at boundary cases, writing operational specifications instead of definitional and stating too much in postconditions. Writing good specifications is a skill that you will work to master the rest of your career. It's hard because the language and compiler do nothing to check the correctness of a specification: there's no type system for them, no warnings, etc. (Though there is ongoing research on how to improve specifications and the writing of them.) The specifications you write will be read by other people, and with that reading can come misunderstanding. Reading specifications requires close attention to detail. Specifications should be written quite early. As soon as a design decision is made, document it in a specification. Specifications should continue to be updated throughout implementation. A specification becomes obsolete only when the code it specifies becomes obsolete and is removed from the code base. Clear specifications serve many important functions in software development teams. One important one is when something goes wrong, everyone can agree on whose job it is to fix the problem: either the implementer has not met the specification and needs to fix the implementation, or the client has written code that assumes something not guaranteed by the spec, and therefore needs to fix the using code. Or, perhaps the spec is wrong, and then the client and implementer need to decide on a new spec. This ability to decide whose problem a bug is prevents problems from slipping through the cracks. The client should not assume more about the implementation than is given in the spec because that allows the implementation to change. The specification forms an *abstraction barrier* that protects the implementer from the client and vice versa. Making assumptions about the implementation that are not guaranteed by the specification is known as *violating the abstraction barrier*. The abstraction barrier enforces local reasoning. Further, it promotes *loose coupling* between different code modules. If one module changes, other modules are less likely to have to change to match. ## Abstraction by specification Abstraction enables modular programming by hiding the details of implementations. Specifications are a part of that kind of abstraction: they reveal certain information about the behavior of a module without disclosing all the details of the module's implementation. *Locality* is one of the benefits of abstraction by specification. A module can be understood without needing to examine its implementation. This locality is critical in implementing large programs, and even in in implementing smaller programs in teams. No one person can keep the entire system in their head at a time. *Modifiability* is another benefit. Modules can be reimplemented without changing the implementation of other modules or functions. Software libraries depend upon this to improve their functionality without forcing all their clients to rewrite code every time the library is upgraded. Modifiability also enables performance enhancements: we can write simple, slow implementations first, then improve bottlenecks as necessary. ## Specifications for functions A specification is written for humans to read, not machines. Specs can take time to write well, and it is time well spent. The main goal is clarity. It is also important to be concise, because client programmers will not always take the effort to read a long spec. As with anything we write, we need to be aware of your audience when writing specifications. Some readers may need a more verbose specification than others. A well-written specification usually has several parts communicating different kinds of information about the thing specified. If we know what the usual ingredients of a specification are, we are less likely to forget to write down something important. Let's now look at a recipe for writing specifications. **Returns clause.** How might we add a specification to `sqr`, assuming that it is a square-root function? First, we need to describe its result. We will call this description the *returns clause* because it is a part of the specification that describes the result of a function call. It is also known as a *postcondition*: it describes a condition that holds after the function is called. Here is an example of a returns clause: ``` (* returns: [sqr(x)] is the square root of [x]. *) ``` For numerical programming, we should probably add some information about how accurate it is. ``` (* returns: [sqr(x)] is the square root of [x]. * Its relative accuracy is no worse than 1.0*10^-6. *) ``` Similarly, we might write a returns clause for a `find` function. It is okay to leave the introductory "`returns:`" implicit: ``` (* [find lst x] is the index of [x] in [lst], starting from zero. *) ``` A good specification is concise but clear&mdash;it should say enough that the reader understands what the function does, but without extra verbiage to plow through and possibly cause the reader to miss the point. Sometimes there is a balance to be struck between brevity and clarity. These two specifications use a useful trick to make them more concise: they talk about the result of applying the function being specified to some arbitrary arguments. Implicitly we understand that the stated postcondition holds for all possible values of any unbound variables (the argument variables). **Requires clause.** The specification for `sqr` doesn't completely make sense because the square root does not exist for some `x` of type `real`. The mathematical square root function is a *partial* function that is defined over only part of its domain. A good function specification is complete with respect to the possible inputs; it provides the client with an understanding of what inputs are allowed and what the results will be for allowed inputs. We have several ways to deal with partial functions. A straightforward approach is to restrict the domain so that it is clear the function cannot be legitimately used on some inputs. The specification rules out bad inputs with a *requires clause* establishing when the function may be called. This clause is also called a *precondition* because it describes a condition that must hold before the function is called. Here is a requires clause for `sqr`: ``` (* [sqr(x)] is the square root of [x]. * Its relative accuracy is no worse than 1.0x10^-6. * requires: [x >= 0] *) ``` This specification doesn't say what happens when `x < 0`, nor does it have to. Remember that the specification is a contract. This contract happens to push the burden of showing that the square root exists onto the client. If the requires clause is not satisfied, the implementation is permitted to do anything it likes: for example, go into an infinite loop or throw an exception. The advantage of this approach is that the implementer is free to design an algorithm without the constraint of having to check for invalid input parameters, which can be tedious and slow down the program. The disadvantage is that it may be difficult to debug if the function is called improperly, because the function can misbehave and the client has no understanding of how it might misbehave. **Raises clause.** Another way to deal with partial functions is to convert them into total functions (functions defined over their entire domain). This approach is arguably easier for the client to deal with because the function's behavior is always defined; it has no precondition. However, it pushes work onto the implementer and may lead to a slower implementation. How can we convert `sqr` into a total function? One approach that is (too) often followed is to define some value that is returned in the cases that the requires clause would have ruled; for example: ``` (* [sqr(x)] is the square root of [x] if [x >= 0], * with relative accuracy no worse than 1.0x10^-6. * Otherwise, a negative number is returned. *) ``` This practice is not recommended because it tends to encourage broken, hard-to-read client code. Almost any correct client of this abstraction will write code like this if the precondition cannot be argued to hold: ``` if sqr(a) < 0.0 then ... else ... ``` The error must still be handled in the `if` expression, so the job of the client of this abstraction isn't any easier than with a requires clause: the client still needs to wrap an explicit test around the call in cases where it might fail. If the test is omitted, the compiler won't complain, and the negative number result will be silently treated as if it were a valid square root, likely causing errors later during program execution. This coding style has been the source of innumerable bugs and security problems in the Unix operating systems and its descendents (e.g., Linux). A better way to make functions total is to have them raise an exception when the expected input condition is not met. Exceptions avoid the necessity of distracting error-handling logic in the client's code. If the function is to be total, the specification must say what exception is raised and when. For example, we might make our square root function total as follows: ``` (* [sqr(x)] is the square root of [x] * with relative accuracy no worse than 1.0x10^-6. * raises: [Negative] if [x < 0]. *) let sqr x = ... ``` Note that the implementation of this `sqr` function must check whether `x>=0`, even in the production version of the code, because some client may be relying on the exception to be raised. **Examples clause.** It can be useful to provide an illustrative example as part of a specification. No matter how clear and well written the specification is, an example is often useful to clients. ``` (* [find lst x] is the index of [x] in [lst], starting * from zero. * example: [find ["b","a","c"] "a" = 1] *) ``` ## How not to write comments In addition to specifying functions, programmers need to provide comments in the body of the functions. In fact, programmers usually do not write enough comments in their code. But this doesn't mean that adding more comments is always better. The wrong comments will simply obscure the code further. Shoveling as many comments into code as possible usually makes the code worse! Both code and comments are precise tools for communication (with the computer and with other programmers) that should be wielded carefully. It is particularly annoying to read code that contains many interspersed comments (typically of questionable value), e.g.: ``` let y = x+1 (* make y one greater than x *) ``` For complex algorithms, some comments may be necessary to explain how the code implementing the algorithm works. Programmers are often tempted to write comments about the algorithm interspersed through the code. But someone reading the code will often find these comments confusing because they don't have a high-level picture of the algorithm. It is usually better to write a paragraph-style comment at the beginning of the function explaining how its implementation works. Explicit points in the code that need to be related to that paragraph can then be marked with very brief comments, like `(* case 1 *)`. Another common but well-intentioned mistake is giving variables long, descriptive names, as in the following verbose code: ``` let number_of_zeros_in_the_list = fold_left (fun (accumulator:int) (list_element:int) -> accumulator + (if list_element=0 then 1 else 0)) 0 the_list in ... ``` Code using such long names will be very verbose and hard to read. Instead of trying to embed a complete description of a variable in its name, use a short and suggestive name (e.g., `zeroes` or `nz`), and if necessary, add a comment at its declaration explaining the purpose of the variable. A related bad practice is to encode the type of the variable in its name, e.g. naming a variable `count` a name like `i_count` to show that it's an integer. Instead, just write a type declaration. If the variable is so far from its type that you can't see the type declaration, the code should probably be restructured anyway. ## Terms and concepts * abstraction by specification * client * comments * example clause * implementer * locality * modifiability * partial function * postcondition * precondition * raises clause * rely * requires clause * returns clause * satisfaction * specification * total function ## Further reading * [*Program Development in Java: Abstraction, Specification, and Object-Oriented Design*][liskov-guttag], chapters 3 and 9, by Barbara Liskov with John Guttag. [liskov-guttag]: https://newcatalog.library.cornell.edu/catalog/9494027