I've been using a testing library based on SRFI-269 quite extensively in
a few projects and I found that during long review or code reading
sessions it's harder to skim, when the description is in tail position
of assertion, so I consider moving it to the front.

Current assertion macro looks like this:

(is (good? something))

It has optional description.

(is (good? something) "something is really good")

It's fine, stable and predictable, however there is a downside for
reading.  The description is supposed to explain what assertion body
actually asserts, when it's not clear or hard to understand from
expression.

In many cases assertion body is simple and understandable, it contains a
predicate and value:

(is (admin? user))

However, sometimes it's a bit move involved, or not clear without broader
context, or contains the expression, which doesn't explain what domain
property we are asserting:

(define status (spawn "touch" "~/test"))

(is (contains? (user-roles user) 'admin))

(is (= status 0))

In this case we either need to define intermediate variable:

(is user-admin?)
(is home-is-writable?)

or add a description.

(is (contains? (user-roles user) 'admin) "user admin")
(is (= status 0) "home writeable")

In the first case the issue is that we need create a lot of intemediate
variables, which is not always convenient in non-trivial tests.

the problem with the second option is that the expression itself gets in
the way of skimming. (I'm not very interested in the implementation
before I understand what domain property we check). So I would like to
read the description first and maybe (only maybe) the assertion code
later.  However, because the description is in the tail position I still
hit the expression first during skimming.

Thus, I consider changing assertion syntax to the following:

(is "user admin" (contains? (user-roles user) 'admin))
(is "home writeable" (= status 0))

For longer expression or clearer reading a new line can be added.

(is "user admin"
  (contains?
   (user-roles user)
   'admin))
(is "home writeable"
  (= status 0))

Pros:
- Most understandable thing appears first (either simple expression or
description)
(is home-writeable?)
(is "home writeable" (= status 0))

- More consistent with suite and test syntax (where description also
goes as the first argument)
- Similiar to Guile's pass-if or SRFI-64 assert-* macros, where optional
description can appear as the first argument.

Cons:
- Not stable assertion body position.
(is "home writeable" (= status 0))
(is (= status 0))

- Assert can silently pass, when the order is mismatched.
(is (= 1 0) "home writeable")

Thoughts?

--
Best regards,
Andrew Tropin