Make it clear and visible in the documentation that the evaluation of side effects depends on the logger

[crumblingstatue]

let mut foo = 0;
log::trace!("{:?}", foo += 1);
foo

This results in foo being 0, because foo += 1 wasn't evaluated.

env_logger::builder()
        .filter_level(log::LevelFilter::Trace)
        .init();
let mut foo = 0;
log::trace!("{:?}", foo += 1);
foo

This will evaluate the side effect, because the logger was initialized.

This behavior can be surprising, and can cause bugs during prototyping, when the user might try to embed expressions with side effects inside log macro invocations, to log their results for debugging purposes. If the logger isn't initialized (for example in a unit test), the side effects will not be evaluated and the behavior will be different than intended.

It should be made clear and prominently visible in the documentation that side effects inside log macro invocations might not be evaluated, depending on the logger's configuration, and so the user shouldn't write expressions with intended side effects inside log macro invocations.

I personally tried to log the result of creating a directory, like so

log::info!("{:?}", std::fs::create_dir("foo"));

And I was surprised when the directory wasn't created when the logger wasn't initialized.

[KodrAus]

It should be made clear and prominently visible in the documentation that side effects inside log macro invocations might not be evaluated, depending on the logger's configuration, and so the user shouldn't write expressions with intended side effects inside log macro invocations.

I think that's fair to call out :+1: We could state it as simply as "Avoid writing expressions with side-effects in log statements. They may not be evaluated".