This is a story about a real macro used by a number of programmers at the Institute for the Learning Sciences for years. It is an example of how not to design and implement a macro.
The creator of the macro was an adept Lisp programmer. He understood how macros worked, how to use backquote to define them, and so on.
A demo of a fairly mature program crashed. Nothing major had been added to it, but a programmer had finished cleaning up its code. After a fair amount of bug hunting, the programmer found the change that broke the code. In essence, he had replaced
(defmacro my-wait-for (n) `(wait-for ,n))
with the seemingly more direct
(defun my-wait-for (n) (wait-for n))
But, with the new version,
(my-wait-for 12) never
waited! Why not?
The Cause of the Problem
The problem lay not with
my-wait-for, but the macro
wait-for. There were three ways to use
- waits for 12 seconds
(foo)until it returns a non-NIL value
(wait-for (baz x y))
(baz x y)until it returns a non-NIL value
The macro version of
(my-wait-for 12) into
which fits the first calling format.
The function version of
the other hand, calls
(wait-for n), with
n = 12. This fits the third calling format,
and is interpreted as "wait until the expression
is non-NIL." Since
n is already non-NIL, no waiting
The Cause of the Cause of the Problem
(wait-for 12) looks like a function call. It looks
like it evaluates its argument. But it is doesn't. It looks at
the argument form to decide what to do.
wait-for is a macro because its designer violated
the principle "one function to a function." He tried to do three
waiting tasks with one interface.
Unfortunately, the first task, "wait for number seconds," shares a common calling format with the third task, "wait for expression to be non-NIL." The rule "do the first task only if the number is explicitly given" is not intuitive, easy to forget, and a pain to live with. For example, it makes it impossible to say
The fix is not to write a comment that says "use only literal numbers for wait times." Where would the comment go? If we put it on the definition, it won't be seen by someone modifying a call to wait-for. And it's pretty unlikely that programmers using wait-for will remember to put a comment on every call to wait-for that says "don't replace this number with a variable!"
Nor is it to change
wait-for to evaluate its argument and, if the result
is a number, do the first task, otherwise do the third. First, this rule counts
on programmers knowing and
remembering that, in wait-for, unlike elsewhere in Lisp, a number is
not treated like other non-NIL values.
Second, exactly what is the rule? If exp in (wait-for exp)
returns nil the first few times, and then returns 3, is that
a signal to stop waiting or a signal to wait three more seconds?
The appropriate fix is to have two waiting forms, e.g.,
number), which is a function, and
(wait-until expression), which is a macro.
Each waiting form can then have simple unsurprising semantics.