@noelrap @alessandrofazzi @geeksam I hear what you're saying. However…

"Usually" means usually. It is a very specific thing in Ruby and its use is limited. That's all I read in that statement. I don't see it as "stay away”. It's more like “if you don't know the difference you probably want that other thing, if you do all power to you”.

As for “this is slow”… It might be slow. If it’s on a hot path you probably should benchmark it. As I said, it's a rather rare thing so it might not have been optimized. Or it might have been. That comment was added 8 years ago, in 2.5. A lot of things have changed since then so that particular part might not hold any more. And it's not like instance_eval docs say “this is fast”. ;)

I'm not blaming you for trusting documentation. After all, that’s the primary source. But documentation is not infallible and some parts of it might be more trustworthy than others.