Assertions As Comments

Once upon a time, assertions were not executable!

 Robert W Floyd
 Assigning Meaning to Programs
 pp19-32 of Proceedings of Symposia in Applied Mathematics Vol XIX 1967

(Von Neumann did them first!)

See also: DesignByContract. See WhatAreAssertions for the post-C meaning.

---

The purpose and effects of a piece of code can often be expressed simply as a non-executable condition written as a comment in a more or less formal language.

As a simple example if you are implementing a method that searches for some target value in an array that you expect to be sorted then you will probably choose to use a binary search. You know that a binary search is normally much faster than a linear search. For this to work you need the data to be sorted.

If the method is invoked when the data is not in order the target may no be found when it is there... and other strange things can happen... To avoid this you might add an executable assertion:

 asserted( sorted(data) );

and code up the function that checks for the data being sorted. If you did this you throw away the speed up. The whole thing runs as slow as a linear search.

So, you could write the property as a comment instead:

 // data are sorted

or more formally

 /*for all 0<=i<=j<data.max, data[i]<=data[j]*/

Similarly you can write comments that explain to your readers what a statement should achieve -- a post-condition.

Sometimes a comment describing something that you know to be true at a particular point in code is worth it. This is called an invariant. This is very powerful in the form of a class invariant: Something that is always true whenever no methods are executing.

A piece of advice to reader. You have to think about AssertionsAsComments in a different way to executable code. Pre-conditions should guarantee that the intervening code ends up at the next one with it being true as a result.

There has been work on having a machine processable comments. The Anna "annotation" language for Ada was an example. The UnifiedModelingLanguage has an ObjectConstraintLanguage or OCL for writing pre- and post-conditions:

 http://www.csci.csusb.edu/dick/samples/ocl.html

Example of OCL as a comment in Smalltalk(please correct my comments below)

 balance
 "pre:  self@pre->sum < maxDollarsStorable "
 "post: result = self@pre->sum "
        ^self
        inject: 0 asDollars
        into: [ :sum :each |sum + each]

Taken to extremes, you end up writing more comments than code, the code works, and people think you are a bit weird. Mail me (DickBotting) and I can send you a URL of an egregious Java example. Such extreme annotation is only valuable when developing an algorithm that will be used in hundreds of programs.

-- DickBotting

---

Compare ExceptionsAsConstraints that claim assertions are comments.

---

I'd prefer the assert over a comment. If it can be expressed in the code, it should be. Use conditional compilation (or related techniques) to switch the check off in normal builds if the speed matters. The assert is typically less ambiguous than English text, and can be easily re-enabled when bug-hunting. -- DaveHarris

---

Surely it would be better to move the assertions to the unit tests rather than comment them out? -- EricUlevik

How would you do that in the "sorted" case? It's a pre-condition, it's saying the routine is allowed, but not required, to misbehave when the input is not sorted. Surely there is no input you could give the routine that would test this? -- DaveHarris

In Smalltalk, if I wanted the input collection sorted, I might do thusly:

 process: aCollection
   ^self processSorted: aCollection asSortedCollection

 processSorted: aSortedCollection
   "private"
   ^etc etc

Since SortedCollections? just answer themselves when sent asSortedCollection, it's fast, clear, and resilient.

From the standpoint of educating whoever next picks up the code, moving all assertions out into unit tests seems like a poor decision. If an assertion describes a useful invariant--one that someone might later fail to glean without careful study--I'll often leave the assertion in primary source, either as a comment or conditionally compiled. Some truly paranoid developement-time assertions lend little value to the reader, and get migrated into test cases. -- DaveSmith

---

CategoryAssertions