So there's this Ruby tool called RDoc that will introspect your project and tell you all about what's inside. Problem solved?<p>Here, look at RDoc's features (from the RDoc website):<p>--Generates structured HTML documentation from Ruby source.
--Authomatically extracts class, module, method, and attribute definitions. These can be annonated using inline comments.
--Analyzes method visibility.
--Handles aliasing.
--Uses non-intrusive and implicit markup in the comments.
--Readers of the original source needn't know that it is marked up at all.<p>Or to come at this from a slightly different angle, don't Ruby's introspection powers provide a release valve for the problems the author is talking about?<p>Anyway, this is just another occasion to state the old adage, "With great power comes great responsibility." You don't have to crapify your Ruby projects if you don't want to. If you need to enforce clarity at all times, I see no better alternative than Python (which I think makes it a better candidate for scientific or math-intensive projects, MRI slowness aside [although I am curious about the implications of genetic algorithms + Ruby introspection]).<p>I do speculate that if you take two programmers of equal skill levels and give one Python and the other Ruby, the Rubyist can gain a productivity advantage over the Pythonista via judicious use of Ruby hackery. But this comes at a cost: it does require more thoughtfulness before execution. Maybe you don't want to think that hard, and that's a totally legitimate and respectable position. In the end, which of the two languages you choose will probably have more to do with personal workflow preferences or project management ideologies.<p>In the case of Rails, yes, it hacks in a DSL and extends Ruby classes, but Rails relies heavily on conventions and things being put in designated areas. It's therefore hard to get lost in a Rails project unless you really have no respect for the conventions (in which case, it doesn't matter what language or framework you're using).