I agree, Perl regexps can often look like a termcap entry, but if a SINGLE
comment line is added immediately before it, it makes it that more
legible.

  And I can't stress enough, use the _right_ tool for the job, whether it
be programming in Perl or removing spark plugs from your '76 Scamp.
You don't use Perl to write device drivers, and you don't pull plugs
using a pipe wrench.

Although commenting is a good idea, it is not the most important thing that
leads to readablity. The most important thing is that you write "good clean
code" making it obvious from the code what your doing. Comments should only
really be needed for bits of "black magic" code (such as Perl regexps) and
for higher level routine descriptions (at the function level in C, or the
subroutine level in Perl). It is possible to over comment, crowding out the
code with comments, making it impossible to see whats happening below. If
you find you can't understand a single routine when its commented this way
its probably either bad code, or you don't know the language well enough.

[...]

--

They gave it me,-- for an un-birthday present.

Seconded. Can I throw in my tuppence-worth: another important thing to do
to ensure readability is to use really descriptive names for variables,
subroutines etc. Sometimes this means long names -- it may be obvious to
you when you write the code that "ader" stands for "action derivative", but
it may not seem so obvious later.

By the way, this doesn't have to mean a lot of typing; for example in emacs
M-/ is invaluable:
dabbrev-expand:
Expand previous word "dynamically".
Expands to the most recent, preceding word for which this is a prefix.
If no suitable preceding word is found, words following point are considered.

This comes from the heart; I've just taken over responsibility for 15000
lines of code (not in Perl) in which the previous programmers have not
followed any of the good advice in this thread. :-(

Perdita

An appropriate quote from Bjarne Stroustrup's _The C++ Programming
Language_ [2nd ed, p 105]:

"The author's preference is for

   1. A comment for each source file stating what the declarations in
      it have in common, references to manuals, general hints for
      maintenance, etc.;

   2. A comment for each class or template;

   3. A comment for each nontrivial function stating its purpose, the
      algroithm used [if non-obvious], and maybe something about the
      assumptions it makes about its environment;

   4. A comment for each global variable;

   5. A few comments in places where the code is non-obvious and/or
      non-portable;

   6. Very little else."

I find that following these rules helps me write much better code.

Fnord,
Tony
--

  "A closetful of courteous anxieties is of dubious comfort."
                                          -- Binkley, _Bloom County_