Clarify use of `assert!` and `debug_assert!` in the documentation

[snowe2010]

A discussion with @gnzlbg lead us to determine that the proper way to use assert! and debug_assert! is confusing. It could be clarified in the documentation as to how they should be used, e.g. proper use in production, proper use for debugging.

[steveklabnik]

I would be happy to work with anyone who wants to tackle this issue

[gnzlbg]

I don't know how easy this is. assert! is used in unsafe code to maintain run-time invariants, that if violated, could lead to unsafety (this use case is a bit advanced).

At the same time, both assert! and debug_assert! are used in both safe and unsafe code to maintain invariants that should be checked (at least in debug builds), but that do not lead to memory unsafety (only e.g. logic errors).

Finally, assert! is also used for unit-testing (with assert_eq!). These are three distinct use cases.

From other programming languages that I know, these second use-case is what I typically relate with assertions. Those programming languages, however, don't have the safe/unsafe code distinction.

I guess I would write something like:

assert! is a macro that ensures the termination of a program if a condition is not satisfied by means of an unrecoverable error (not necessarily a panic!, can also be an abort). Assertions are always checked in both debug and release builds, and cannot be disabled. Unsafe code relies on assert! to enforce run-time invariants that, if violated, could lead to unsafety.

Other use-cases of assert! include testing (with a link to testing) and enforcing run-time invariants in safe code (whose violation cannot result in unsafety). The debug_assert! macro allows disabling checking for the assertions at build time (debug_test = false). An unchecked assertion allows a program in an inconsistent state to keep running, which might have unexpected consequences but does not introduce unsafety as long as this only happens in safe code. The performance cost of assertions is, however, not measurable in general. Replacing assert! with debug_assert! is thus only encouraged after throughrough profiling, and more importantly, only in safe code!

[steveklabnik]

I guess my thinking is that this is technically easy: you just have to know where to add the text. Part of what I imagine working with someone on here is exactly how it's presented.

On Jun 27, 2016, 19:40 -0400, gnzlbgnotifications@github.com, wrote:

I don't know how easy this is.assert!is used in unsafe code to maintain run-time invariants, that if violated, could lead to unsafety (this use case is a bit advanced).

At the same time, bothassert!anddebug_assert!are used in both safe and unsafe code to maintain invariants that should be checked (at least in debug builds), but that do not lead to memory unsafety (only e.g. logic errors).

Finally,assert!is also used for unit-testing (withassert_eq!). These are three distinct use cases.

From other programming languages that I know, these second use-case is what I typically relate with assertions. Those programming languages, however, don't have the safe/unsafe code distinction.

I guess I would write something like:

assert!is a macro that ensures the termination of a program if a condition is not satisfied by means of an unrecoverable error (not necessarily apanic!, can also be anabort). Assertions are always checked in both debug and release builds, and cannot be disabled. Unsafe code relies onassert!to enforce run-time invariants that, if violated, could lead to unsafety.

Other use-cases ofassert!include testing (with a link to testing) and enforcing run-time invariants in safe code (whose violation cannot result in unsafety). Thedebug_assert!macro allows disabling checking for the assertions at build time (debug_test = false). An unchecked assertion allows a program in an inconsistent state to keep running, which might have unexpected consequences but does not introduce unsafety as long as this only happens in safe code. The performance cost of assertions is, however, not measurable in general. Replacingassert!withdebug_assert!is thus only encouraged after throughrough profiling, and more importantly, only in safe code!

—
You are receiving this because you commented.
Reply to this email directly,view it on GitHub(#34455 (comment)), ormute the thread(https://github.com/notifications/unsubscribe/AABsiqa3I1j4AWbZYSHudcR5UbdsHOrWks5qQF-GgaJpZM4I991n).

[munyari]

@steveklabnik I'd like to work on this with you. Where should one begin?

[steveklabnik]

@munyari great! So, https://github.com/rust-lang/rust/blob/master/src/libcore/macros.rs#L33-L60 and https://github.com/rust-lang/rust/blob/master/src/libcore/macros.rs#L111-L145 are where the text goes.

What do you think about @gnzlbg 's draft of the comments? Feel free to open a PR (I can help walk you through that too if you need) with it, or some variant of it, in your own words, and we can go from there 😄

[munyari]

Just opened a PR @steveklabnik 😄

[brson]

Thanks @munyari !