From: Dave Fayram <dfayram@...>
Date: 2005-04-28T08:04:30+09:00
Subject: Re: Comments Are More Important Than Code

Go to http://ar.rubyonrails.com/classes/ActiveRecord/Base.html and just
nose around.

Then go to
http://dev.rubyonrails.com/file/trunk/activerecord/lib/active_record/base.rb
which is the corresponding source file.

Note how there is tons of documentation of what the library can do, and
how you can use it, but the functions themselves contain very little
documentation. To me, this is the way to go, especially with tested
code. It makes it maintainable (thanks to the tests and the
documentation that shows you what to expect.

This is what I consider to be good documentation. Rails is a
particularly good case because it's a non-trivial library that recieves
many, many patches. Often these patches even come from Ruby-Nubys. So
clearly, Rails is easy to maintain (if a language novice can submit
meaningful patches within a week, it's easy code). Yet it lacks the
kind of documentation that the essay says it should have.

I have no way to reconcile this discrepency except to say that maybe
all that inline documentation regardign what algorithms are used and
why is extraneous and therefore, a waste of time.