Welcome! Please see the About page for a little more info on how this works.

+11 votes
in Docs by

The {{assert}} macro has two arities, documented as {{(assert x)}} and {{(assert x message)}}

The docstring is:
Evaluates expr and throws an exception if it does not evaluate to logical true.

This is quite misleading since {{assert}} actually throws an {{Error}}. It is tempting to use {{assert}} assuming that a failure will lead to a stacktrace in logs, like any other {{Exception}}, but the reality is that the JVM will terminate.

The behaviour is correct, {{assert}} should cause a program to exit if the asserted condition is true but I regularly come across incorrect uses.

I'll work up a patch if people agree this is an issue.

4 Answers

+3 votes

Comment made by: marc

There is one further omission in the docstring (both current and proposed) - neither mention that the behavior of assert depends on the value of the clojure.core/**assert** dynamic var.

+1 vote

Comment made by: gordonsyme

clj-2225-20170913.patch updates the assert macro docstring. I've wrapped the docstring at 70 characters, it seems to be a fairly common width used throughout the rest of the file.

+1 vote
Reference: https://clojure.atlassian.net/browse/CLJ-2225 (reported by gordonsyme)
0 votes

Comment made by: alexmiller

Error is a subclass of Throwable, just like Exception and has no special behavior (although it does have the special intended meaning that most programs should not catch it). Whether or not your program does catch it, or exit, or log, is totally up to your program and not a property of being an Error.

The only change that I think might make sense here is to be more specific about the exception type.