Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
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.

In reply to Maintainable code is the best code by dragonchild

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or or How to display code and escape characters are good places to start.
Log In?

What's my password?
Create A New User
Domain Nodelet?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others contemplating the Monastery: (4)
As of 2021-12-07 10:14 GMT
Find Nodes?
    Voting Booth?
    R or B?

    Results (33 votes). Check out past polls.