For most of the last 20 years or so, I have dealt with existing systems; usually, they are projects in trouble.   They may be in Perl or in some other language; usually, they are in several.   They average about 70,000 lines long depending on exactly how you count lines.   They are considered long-in-the-tooth, but they are still mission critical, and of course the original programmers are long-gone if not dead.   These programs invariably share the following characteristics:

1. They were (of course) built for much more-limited hardware; therefore ...
2. They were “clever,” and, quite frankly, as a result ...
3. They are unmaintainable.   (Mind you, they didn’t start that way, and they were competently written, but that is their present-state today.)

Every piece of computer software starts out pristine and beautiful in its creator’s mind, perfectly adapted to both the hardware and the business needs of their first birthday.   Trouble is, software lives forever, and it gets very old very fast.   (Which is why the customary suggestion is that we should just scrap it all and start over.)

Being, as I am, more-or-less in the position of a coroner (except that the software is still alive and will remain so), I’ve learned a lot about the blowflies in the computer software life-cycle.   I get to pore through the source-code of a long-gone person to reconstruct, with no reference sources available other than that source-code, both what the software does and how to extend what it does.   (I also get to mop-up after, say, “Agile” teams that had no idea what they were doing but who did it anyway.)   Well, I could talk at some length about the project (non-)management and seat-of-the-pants (non-)design problems that often lead to crappy sub-optimal software in production settings, but for now let’s just briefly talk about how you write your code.

I’d like to point out a few things that Perl coders can do which make my chosen career much easier.   Even though all of these are very simple things, they make a tremendous difference ... and they are rare.

First and foremost:   do not be clever ... instead, be clear.   That’s definitely the “biggie.”   Your job is emphatically not to win a game of “Name That Tune.”   Your job should be above all to write code that can be reliably understood at a glance.   Comments are free in all languages.   Tell me what you were thinking at the exact time you wrote this.   Tell me when.   Tell me why.   Tell me:   the designer’s intent.

Second:   Design for maintainability.   The future, of this software, will be here soon enough, even if you are not.   The biggest bugaboo of “clever code” is that when, not if, a different requirement comes along, you can’t just add new source-lines at a readily identifiable and functionally isolated spot in the code.   (Obviously, the preceding statement could be taken to the point of absurdity, so don’t go that far.)   The essential trouble here is that you sometimes have to substantially change code that is working in order to introduce new functionality ... and have you ever tried to take apart a pocket watch?   If your code needs to make some determination about a complicated text-string, please make that determination once and only once, then set a variable to a value that carries that information forward.   Use constants.   Use enumerated types if you have them.   I love to see code that is distrustful of its inputs, because that gives me confidence that those inputs at runtime must be correct if the tests are correct.   I am usually not dealing with performance-critical code, and I am usually trying to find out, among other things, why proper code (when viewed in isolation ...) is producing the wrong answers.   If you just made this thing up by the seat of your pants, I know it.   (Sorry, but I do, because now I have to reconstruct your fragmented and chaotic thoughts using your fragmented and chaotic code.)

Third:   Compartmentalize your code as much as practicable.   Try to put the code that does just one thing in just one place.   Try to use consistent nomenclature for everything.   Please use a source-code version control system, and please make meaningful comments in it.   If you also use a trouble-ticket system, mention that ticket number in your commit notes.

Fourth:   Be sure the code does not contain invisible errors in the source code.   Perl is bad for this, but so is FORTRAN.   In Perl, use strict; use warnings; is mandatory.   I’m looking at the code, not running it.   Make sure that the code “looks” clean, and is consistent and easy-to-read, otherwise I have to run it through a “tidy” program and I do not like to reformat things for risk of losing something.   (You have seen this yourself:   someone posts a piece of code for assistance, and someone promptly says that it contained syntax errors and such that the author didn’t know about.   Hence, his or her understanding of what the code would actually do or was actually doing was incomplete ... and we are talking about the original author.   My position is identical, only much more precarious.)

Fifth:   “TMTOWTDI™ ??   Great!   (Big deal.)   Pick one.”   The less time spent deciphering how you did it, or worse yet, deciphering more than one way you did it, the better the understanding of the code will be ... and the less chance that the analysis of what to do next will be flawed by some unknown-to-you difference between one and the other.   I want to learn what made you tick, and to recognize your modus operandi each time I see it again.   I learn to recognize people by the distinctive signature of the code they write.   (I might dub you Kukla, Fran, or Ollie.   No offense.)

I could go on, but, if you are also in the business of software project turnarounds, let me instead now hand over the bully pulpit to you.

Remember ... if you are one of the original coders when I first encounter the system, I can’t dig you up and ask you a question.   (And I’m not necessarily joking.)