[Pdx-pm] Readable code

[Austin Schutz]

> I've gotten in the habit of breaking my code out into lots of 
> subroutines because I've found that makes it much easier for me to read 
> and troubleshoot, a practice that seemed to be reinforced in Code 
> Complete. Now, however, as I read books on Perl and talk to Perl coders 
> I'm finding that placing an emphasis on writing readable code, and 
> breaking code out into lots of subroutines doesn't seem to be 
> considered "the Perl way" of doing things. The emphasis seems to be 
> tighter and tighter code, sometimes - it seems to me - at the expense 
> of readability (especially for those new to Perl).
> 

	Actually, I'd have to say by and large the documentation in the
published code, except for the Tolkien peppered C, has improved quite a bit
over the last few years. Either that or I'm having an easier time slogging
through it.


> I'd be very interested in your thoughts and suggestions regarding terse 
> code, readable code, verbose code, etc...
> 

	I tend to be one of those annoying long sub people, though I
do my best to document what a sub is supposed to accomplish and how each
section works toward accomplishing that goal.
	Deciding how long to make subs is pretty subjective. There's a
readability tradeoff either way - either you have long subs which run
on and are more difficult to debug, or you chop it into smaller blocks
which may be harder to comprehend and lead to more complex code paths.

	Here's an example of what I mean. Take a lexer, for example. You
tend to have sections like:


if (/a/) { ...
} elsif (/b/) { ...
} elsif (/c/) { ...
...
} elsif (/z/) { ...


	Which could be shortened to:

if(/[a-l]/) { lex_a_l();
} elsif( /[m-z]/) { lex_m_z();
} else { ... }

	but you've added complexity, and it may be harder to follow the
code in the end, especially as you get more and more levels deep.

	I dunno. Use common sense, try to imagine what the poor slob
who gets to maintain your code will want to know when reading it. Chances
are you will end up being the poor slob as soon as you've forgotten how
the code works and something breaks.
	Use pod to doc functionality. pod rocks.

	Austin