Dave Fayram wrote:
> 
> If you want to explain why you did something, that's what a whitepaper
> or tech memo is for. Your code isn't the place to justify your position
> post facto. The fact that the code works should be justification
> enough. :)

Yeah; I've written lots of code that, um worked.   It just  worked at 
the wrong thing.

> 
> Inevitably, the documentation-heavy approach (comment-driven
> development) leads to a design-up-front methodology. And I think we
> have a mountain of evidence that the Waterfall Method and similar
> up-front design methodologies are impractical at best.

I don't see how one goes from writing comments to having a 
documentation-heavy approach.  Or how it equates to up-front design.

> 
> I'm a big fan of documentation and code that lends itself to the
> reader, and Ruby helps me with this, but my feeling is that if your
> methods are so long that they require comments, then your methods are
> too long. Sure, there are exceptions to this (explaining a tricky step,
> saying why a non-obvious piece of code exists, naming a pattern or
> algorithm), but in general I think this is a reaction to bad coding
> practice.

But a better approach might be to write the method comment first, then 
convert the comment to code, such that the comment is no longer needed. 
  And if you find that you cannot do this, then that may be a code smell.

Or, the comments that remain are higher-level observations that have no 
code equivalent, and should stay.

I believe that developers can forget that what seems obvious at the time 
the code is written will often seem cryptic later on, ever to the one 
who wrote it.  Writing it down forces you to at least make the point 
explicit, and help the coder see if he or she has a clear understanding 
of what code is supposed to do.

I find the a best way to know if I understand something is to try to 
write about it.  It forces me think in a certain way that talking or 
coding does not.

Writing is a unit test for the brain.

> 
> I really like the Ruby communitiy's approach to documentation. Document
> *what* functions do, give examples of class usage, provide rich unit
> tests. But seldom do I see a project give step-by-step comments,
> explain what variables are (beyond their name), or explain motiviations
> in the code. This means we have beautiful Rdoc outputs and clean code.

That's great when it happens.  But there is too much core ruby rdoc that 
simply gives an obtuse method and a set of terse variable names. Not a 
word on what the method does.

> 
> Strictly speaking, the Rails documentation would fail this guy's
> criterion for good documentation. But I think pretty much anyone who's
> used Rails (and gotten past the awkward, "Where do I start" step) can
> testify that the Rails documentation is complete and well-done.

Not everyone agrees with that.  I'm past the "Where do I start" step and 
routinely have problems understanding how to do what should be simple 
tasks.


James


-- 

http://www.ruby-doc.org
http://www.rubyxml.com
http://catapult.rubyforge.com
http://orbjson.rubyforge.com
http://ooo4r.rubyforge.com
http://www.jamesbritt.com