Dave Fayram
4/27/2005 6:27:00 PM
I actually sat down and read this artcile. I'm blown away by some of
the things he said. I'm so blown away that I am going to rant a little.
I hope no one minds. <:)
For example:
> Any language or system that does not allow full flowing and
> arbitrarily long comments is seriously behind the times. That
> we use escape characters to "escape" from code to comment is
> backwards. Ideally, comment should be the default, with a
> way to signal the occasional lines of code.
What he said up there, that's crazy talk. Ramblings about Literate
Programming aside, the idea that documentation should come before code
is a serious mistake. Documentation exists to *document code*, code
does not exist to follow documentation.
Then he rambles about "bad" comments and makes some trivial examples.
Then he puts in an example which he asserts is good, but doesn't really
justify why it's good to explain your algorithm choice in the code.
It's not unreasonable to name algorithms or patterns in your code, but
the "why" has no place in there, because that "why" is subject to
change and is outside the scope of the program itself.
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. :)
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'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.
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.
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.