Re: improving the aesthetics of perl code

I didn't intend for this to turn into a style guide, but it seems I've written one. Hopefully, it will prove helpful.

Ytrew's Top Ten Style Points

As others have mentioned, spelling and grammer are very important. Learn to express yourself in English, first. Then move on to programming.

Well written code should read very much like English prose. Think of each statement as a sentence. Variable names are like nouns. Function calls and operators are like verbs. Functions and code block are like paragraphs. If you choose the right "words" and "sentences", your code will be easy to read.
If you can't understand a statement without pausing to think, re-write it. If it isn't obvious why the statement is in the current function, document the function better. Explain how the statement fulfils the purpose of the function. If the statement doesn't have anything to do with the function's purpose, move it elsewhere or delete it.

Use function calls. If you can make your program more self-descriptive by wrapping a block of code with a meaningful name, do it. Even if the function is only a single line of code, if it's complicated enough, it belong in it's own function. Remember, function calls are fast. Computer time is much cheaper than programmer time. You can optimize parts of your program later if it's slow: but you can't optimize what you can't understand.
Not every line of code belongs in a function, of course. Optimize to minimize confusion: if a descriptive name is more clear than reading the corresponding code, the code belongs in a function of it's own.
Document your functions. Explain their purpose, their limitations, and any assumptions about how they will be used or called. Explain any side effects. Document the error handling (and think about error handling).

Avoid vague variable names, such as "verbiage". Every aspect of your program should contribute to the documentation of your program.
Even if you're throwing away a big section of "junk data", make what you're doing and why as clear as possible. The variable names should explain what the source of the data was. The search or filter function call should explain what data you want to keep. The pod documentation for the calling function should explain the requirements for the function. Based upon those requirements, it should be clear why you need to keep the data : if it isn't, document it.

Write for code maintenance. Keep expressions short and simple. It's easier to debug expressions that have been broken down into sub-expressions. It's also often easier to prove them correct. And English style guides say that short sentences are easier to understand than long ones. That's true in Perl, too.

Use pod for documentation. In my code, I keep the user documentation (how to run the program) distinct from code's documenation. I still use pod for both.
I use normal pod for the user documentation. That way, "perldoc <programname>" always explains how to run the program.
For the code documentation, I use a special feature of pod. I mark my code documentation with the '=begin <translator>' and '=end <translator>' pod directives. (I call my translator program "programerdocs".) My programmerdocs pod translator program just translates 'programmerdocs' lines into normal pod, by adding an '=pod', then filters them through the normal pod translator. This way, I can maintain two independent sets of pod documentation: one for end users, and one for coders and testers.
My goal is that a skilled tester could take the internals documentation, and write unit/integration tests for all the functions, without ever reading a line of code. If they can do that, I know it's properly documented.

In general, avoid the use of constants. If you have to use them (such as hardcoding a list for security), put them at the front of the function so they can be found and updated quickly by a code maintainer.

Not many people seem to do this, but I like to comment the terminating brace of function calls, if statements, loop constructs, and so forth. I generally try to take the opportunity to sum up the purpose of the construct, restating what the purpose of the matching section was. Again, I'm trying to avoid work for the mainance coder.
If you need to add a statment before the end of a loop, would you rather see:
```
     }
    }
}
}
[download]
```
or
```
        } # end loop over records from input file
   } # end loop over files
} # end read_records()
} # end block of variables private to read_records()
[download]
```
It also helps me out when I have a program with one too many or too few braces: I can quickly match what a brace actually does match with (using % in vi), and compare against what it should match.

Code so that the most junior programmer understands. Sometimes it helps to wander over to the desk of someone who knows less Perl than you do. Ask him/her which of two alternative Perl expressions are simpler to their eyes. Repeat with all the junior coders you can find. If there's a majority opinion, respect it. If a novice can understand your code, an expert can, too.

However, write for your intended audience. If everyone at work is a Perl guru, and there is a corporate standard that requires a given skill level for Perl hires, then you can assume more knowledge about Perl in your documentation.
Never assume your audience knows your project's business rules, implicit assumptions, or so forth unless there is an excellent reason to assume this will be true. Remember that programming staff come and go, so try to ensure that the costs of excessive documentation are balanced against the risks of information loss.

To sum up: make every aspect of your code a form of documentation. Don't use $_ when you could use a more meaningful name. Try coding defensively: will your current line of code still make sense after someone else throws 100 lines badly formatted code in the middle? If so, then the code is probably self-documenting enough.

The most useful book on programming that I ever read was called "Debugging C": it taught that the most effective way to debug programs was to write them in a simple, straightforward way in the first place. It's very good advice.

Good luck! Keep practicing! The first step towards better style is trying to learn!

--
Ytrew Q. Uiop

Comment on Re: improving the aesthetics of perl code Select or Download Code

Replies are listed 'Best First'.
Re^2: improving the aesthetics of perl code by Anonymous Monk on Jan 22, 2005 at 07:42 UTC
The fat cat sat on the mat. The fat cat was tired. The fat cat had just eaten. The fat cat ate a lot. That made the fat cat sleepy. The fat cat went to sleep on the mat.	[reply]
Re^3: improving the aesthetics of perl code by Ytrew (Pilgrim) on Jan 22, 2005 at 22:33 UTC
The fat cat sat on the mat. The fat cat was tired. The fat cat had just eaten. The fat cat ate a lot. That made the fat cat sleepy. The fat cat went to sleep on the mat. It is far better to write the simplistic text above than the purportedly "more adult" text below, in my opinion. "The aforementioned creature, grown senecent in the ways of corpulence, had taken up residence upon an entanglement of fibrous matter. Bestirring itself to the siren call of the Sandman's lair, it gravitated in a state of satiety, brought on by an act of pedestrian consumption, noteable only by it's excess. Led thereby to the banquet of Morpheus, it took up the preoffered cup, paused, and drank deeply." The second paragraph is similar to a lot of code I see in the world today: it suffers from trying too hard. It has several faults. It's excessively wordy. It uses too many confusing metaphors. For example, "Morpheus's banquet" refers to sleeping, not eating.(Morpheus was the ancient greek God of Dreams.) It contains both grammar mistakes ("it's" rather than "its") and spelling errors ("preoffered" is particularly confusing, as it looks like "pre-offered" rather than "proffered"). It also fails to mention that the creature in question is really a cat. Given that the story is about the cat, it's a major flaw. Suppose I hire a 14 year old kid as a junior editor. If I tell him "change the cat from fat to thin", and "make him drink, not eat", I know he can fix the first story with ease. I also know that he'll have a harder time with the second story: it will cost me more money, because he'll get confused, and take longer trying to figure it out. It would take a lot of editing to fix the second story. If I were to edit the original text, I would find that there's not as much wrong with it. The word "fat" is repeated needlessly. The paragraph doesn't stand alone: it assumes that a specific cat has been previously identified, by the use of the word "the" rather than "a" when refering to the cat. The notions of sleep and causation are repeated. I would probably write the story as: "Once upon a time, there was a fat cat. The cat sat on a mat. It was sleepy, because it had just eaten a lot. So, it went to sleep on the mat." Note that it's still readable by a grade school student, or by a non-native English speaker. I've taken seven years of French in school, and I still stumble when trying to read children's books. I imagine non-native programmers feel similarly with English. Remember, the purpose of programming is not creative expression, but rather clear exposition. The CPU needs to know what to do: the maintainer needs to know why you did it. No one needs to know that you passed grade 13 English with a 97% average (except maybe your university English professor). -- Ytrew	[reply]
Re^4: improving the aesthetics of perl code by Anonymous Monk on Jan 23, 2005 at 00:42 UTC
The overweight cat was feeling drowsy having eaten a large meal, and lay down on the mat to sleep. Concise, joined up, complete. Software constitutes some of the most complex creations of man. Writing software is one of the most challenging endevours man undertakes, and requires education, skills and experience to do well. You would not employ a lawnmower service apprentice to work on your Lexus or Mercedes. Or a flight attendant to fly your 767. Nor a med. student to perform open heart surgery. Why would you employ a 14 y/o to edit anything important? Equally, employing unskilled, or semi-skilled persons to maintain your business software, and deskilling your programmers to write baby code in order that you can, is stupid and counter productive. If you dumb down the code, the maintenance programmer will never aquire better skills. Supervise their work and train them. The rewards will outweight the costs. "No one needs to know that you passed grade 13 English with a 97% average" Then why is your highest priority item? "As others have mentioned, spelling and grammer are very important. Learn to express yourself in English, first."	[reply]
Re^5: improving the aesthetics of perl code by Ytrew (Pilgrim) on Jan 23, 2005 at 21:23 UTC
Re^6: improving the aesthetics of perl code by hv (Prior) on Jan 24, 2005 at 14:19 UTC
Some notes below your chosen depth have not been shown here
Re^6: improving the aesthetics of perl code by Anonymous Monk on Jan 24, 2005 at 14:57 UTC
Some notes below your chosen depth have not been shown here