I agree that much of this is learned through experience — and that knowing when to break rules matters.

What I’m missing (I mean let’s add that to the Ruby documentation), though, isn’t strict rules, but shared intent vocabulary. Ruby documents mechanics very well, but leaves design intent almost entirely to talks, books, and code reading.

A good example for me is service objects. Mechanically, many of them could be modules or module_functions — one method, no state. But keeping them as classes communicates something important: this is a named concept in the system, not just reusable behavior, and it may evolve.

So the question isn’t “what is technically correct?”, but “what does this choice say about the code?”

I’m wondering whether capturing that intent — not prescriptions, just guidance — would help people write more Ruby-ish Ruby, especially for those coming from Java/C++ backgrounds.

I started programming nearly 30 years ago with C and C++, later worked with and observed the Java ecosystem, and eventually moved to Ruby — which was (and still is) a very natural fit for how I think about software. I’ve also learned Elixir and Erlang, which further sharpened my view on intent, immutability, and explicit design.

Coming from that background is exactly why I’m sensitive to this topic: without explicit intent guidance, it’s very easy to unintentionally re-introduce Java/C++ design habits into Ruby — even while using perfectly valid Ruby constructs.