Subject: Re: switch to two-argument KASSERT?
To: Matt Thomas <>
From: Daniel Carosone <>
List: tech-kern
Date: 01/15/2004 21:11:02
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Wed, Jan 14, 2004 at 02:16:14AM -0800, Matt Thomas wrote:

> For instance, I'd convert:
>         KASSERT(j < 8);
> to:
>         KASSERT2(j < 8, ("pmap_spill_pte: assertion j (%d) < 8 failed",=
> j));
> Having j < 8 again is useless. =20

I think this illustrates my point exactly.  Your longer string doesn't
tell me much that "j < 8" wouldn't, once the surroundings are taken
care of:

 - "pmap_spill_pte" would be in the stack trace
 - "assertion .. failed" can be in the macro and needn't be typed
   every time
 - j < 8 is just the cond string
 - (%d), the actual value, may well be useful.

The practice I try to encourage is a little different, and having most
of the above information automatically in the assertion message leaves
the programmer without an easy "cop out" message that just rephrases
the condition in semi-english.

Instead, the idea is that the programmer should put in text explaining
*why* the assertion should be true, or what's wrong, outside the
direct value of the condition.

 KASSERT( j < 8, ("%d legs is too few for an octopus", j))

This lets readers of the string understand what the programmer was
thinking (either when generally looking at the code, or if the
assertion fires), especially if they weren't thinking clearly and
forgot that they have to handle injured octopodes.

Good assertions are some of the best documentation.

Content-Type: application/pgp-signature
Content-Disposition: inline

Version: GnuPG v1.2.4 (NetBSD)