Ok, there is one thing that I absolutely HATE about Ruby -- Code can end up everywhere!  Yes, this is a wonderful and very powerful piece of functionality in Ruby: you can modify anything and everything to fit your needs.  However, if you aren't careful, you end up with completely unreadable code.

This is one reason I like Java, if I want to know about some detail that isn't in the API (we'll get to that Ruby issue in a second), I know exactly where that method is going to be.  This is something that I do allot.  I like to know exactly what my code is doing.  For many reasons, I just don't trust other developer unless I know them really well.

About Ruby APIs (Note, I'm not talking just about THE Ruby API, but APIs for Ruby in general): DOCUMENT EVERY METHOD -- I don't care if it's a private method or a one liner that simply makes your life easier -- document it!!  Why?  Because I may want to know what it does, and if it's not in your API, I've got to go find it, and that's a pain in Ruby.

So, here are 2 Ruby Best Practices that some Ruby developer forget:

1. Use good file naming conventions and separate code into multiple files.  One module, one class per file.  If you class is named AClass, your file should be named a_class.rb.  If you have AClass inside module AModule, a_class.rb should be inside the directory a_module.
   
2. If you define or redefine it -- document it.  Use the :nodoc: sparingly

Posted by: Travis