--d8Lz2Tf5e5STOWUP
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:
>=20
>         KASSERT(j < 8);
>=20
> to:
>=20
>         KASSERT2(j < 8, ("pmap_spill_pte: assertion j (%d) < 8 failed",=
=20
> j));
>=20
> 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.

--
Dan.
--d8Lz2Tf5e5STOWUP
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (NetBSD)

iD8DBQFABmc2EAVxvV4N66cRAsuKAJ0Ra0NccS4OMhUCY3LjlvhN39QRxQCgn1j7
7WYL5OCiO9JzB2SKH2KkVGA=
=Fyju
-----END PGP SIGNATURE-----

--d8Lz2Tf5e5STOWUP--