From: Dave Thomas <Dave@...>
Date: 2000-10-15T00:36:09+09:00
Subject: [ruby-talk:5535] Re: 2 ideas from Haskell

Mark Slagell <ms@iastate.edu> writes:

> Would you at least agree that there are some good exceptions beyond the
> "architectural level decisions" you mentioned?  Surely regular
> expressions, except in the very simplest cases, deserve short
> natural-language summaries.

I'm not sure. If I document a regexp, it'll be something like:

   # extract the name and SSN from the blurble record
   record =~ /....

Documenting it at a lower level seems redundant. Why? Well, if you
want to change it, you're going to have to parse it anyway, and if
you're not, then the high level description would probably be enough.

However, I _do_ use /x to allow me to add whitespace to make regexps
more readable, and hence more self-documenting.

> Thanks for articulating this by the way.  I've not heard anyone argue
> your position before and so hadn't really been aware there was another
> position.  So a relative lack of comments doesn't necessarily indicate
> somebody being undisciplined, inconsiderate, or worst of all, living by
> the "if it was hard to write, it should be hard to read" rule?  Ya learn
> something new every day. :-)

We actually wrote about the dangers of over-commenting in Pragmatic
Programmer. In fact, in a past life I used to be a person who wrote
moe comments than code. I had beautifully formated comment blocks
everywhere, and emacs marcos that let me edit them. Then one day I
realized that whenever I changed a program, I was spending more time
maintaining the comments than the code, and the only time I ever read
the comments was when I was changing them. So I tried cutting back,
and I've found that I don't miss them at all.


Regards


Dave