http://qs321.pair.com?node_id=116172

There have been a number of posts regarding coding style and coding efficiency. I'd like to weigh in on this topic.

The most efficient applications coding practice is the practice that leads to the most maintainable code.

Now, obviously, writing one-offs doesn't come under this. However, I'm not talking about one-offs. I'm talking about applications. Even applications as small as a two-form website. Anything you might want to revisit to make a single change in ... that's what's covered.

Now, maintainabilty is a very large topic, covering a number of coding practices. But, there are a few items which every piece of maintainable code has.

  • Factored / Orthogonal functions/scripts
  • Readable - this includes (but is not restricted to)
    • Descriptive variable names
    • Descriptive function names
    • Consistent indentation/bracketing (whatever style you choose)
    • Minimally sufficient commenting, explaining what variable names do not
    • Sufficient whitespace

I'll take each one separately.

Orthogonal functions are functions which have the following properties:

  • They do one thing
  • They do only one thing
  • They do that thing well
  • They do not depend on global variables

This leads to functions that are completely understandable in and of themselves. They do not depend on anything but that which they are given. This means that a function's purpose can be understood, then you never need to refer to it again. These are also known as atomic functions.

Factoring is the process by which one attains orthogonal functions. You "factor out" atomic concepts and make a function out of them.

You could very easily have a function that normalizes a name. Even if it's only called in that one place in your code, you still want to make a normalizeName() function. This means that your main loop has less clutter in it.

Readability. This is a topic that has a lot of people up in arms. However, there seem to be a few common sense things you can do to make your code more readable, and thus more maintainable. For example

my %hash1; #Hash for stuff my %hash2468; #hash for even nos my@blahblah; # Is this even necessary? my %someOtherKindOfHash; # Maybe stuff here my %h3; #you might want this hash, too.
That is a complete mess of a declaration of global variables. Yet, I see this over and over in code I'm given. Instead, why not do something like
# Predeclared hashes. Used throughout the script. my %hashForStuff; my %hashForEvenNumbers; my %hashForEvenMoreStuff; my %hashThatIThinkIMightNeed; # Is this even necessary? # my @blahblah;
I personally think that this is night and day. The useless comments to the right are gone, reducing the white noise. The variables tell you what they're for. There is a single comment giving useful information that the variable names do not. Even more, one section is for hashes and another for arrays. Breaking declarations up in some logical fashion, either by type of variable or what the variables will be used for, is extremely useful. It gives your reader more information.

The same goes for function names. If your function is determining the validity of a value, call it isValidValue(). This way, you end up with code that look like

if (isValidValue($num)) { # Do stuff here. } return undef unless isValidValue($num2);
It's almost like reading English! That is readable code.

Now for whitespace. Use whitespace intelligently. It not only tells your reader (who, most likely, will be you!) what things are separated from what, but also by how much. For example, if you use one line to separate while loops, that tells your reader that you're still in the same main concept. However, if you use three lines, that's telling the reader that you're shifting gears and doing something new.

I'll be writing another meditation on some of the Perlisms that can make your code much more readable.

Update: I agree completely with theorbtwo's comments regarding the variable naming. What I was trying to accomplish was to indicate that grouping like things and getting rid of the right-side comments would improve readability 10-fold. I should've taken it the next step and come up with good variable names. I got lazy. *winces* :-)

Also, as per hsmyers, Minimal changed to Sufficient above.

After discussions with tilly, Sufficient changed to "Minimally Sufficient". I feel that this is better than "Minimal" because minimal could imply "least possible", which may not convey all the necessary information.

------
We are the carpenters and bricklayers of the Information Age.

Don't go borrowing trouble. For programmers, this means Worry only about what you need to implement.