|No such thing as a small change|
A guide to coding Perlby rir (Vicar)
|on Dec 11, 2002 at 03:31 UTC||Need Help??|
These are my programming guidelines. These are idiosyncratic. This list is taped to my monitor. Since my team is just me my list is more of a cheat sheet.
I revise this list fairly often, a few times a year. It lists what I consider important in coding, what I need reminding of, and found tidbits to be integrated somehow/where/time.
The list items are short so it can live on the bezel of my monitor and so meanings may become overloaded. Here I have added annotations to clarify my abbreviated notes.
The list order is significant. Things will creep on and off the list as their applicability to my code is discovered or as I integrate the item into my code or mindset. For instance Avoiding premature optimization would be on this list, but that is not a problem for me. I've sworn off.
1. Do your best
This just cannot be over emphasized. I don't feel I have a problem with doing quality work, but bringing the issue up focuses me on the task. I am less apt to wander off into some other activity.
Proper function of the code is the primary issue. Best & test just go together: assertion & evidence, spaghetti & sauce.
I find I never test too much. My bad habit is to throw away little tests that could go into the testing regime.
Test as play or try. Not sure how pack() works? Try it, see how it works. Often I see questions here about the usage of a function or operator, that show enough insight, that I wonder why the questioner didn't just write a short page of code and see for himself. Having or developing this quality is a key element to being a good programmer. It shows the right attitude, a pleasure in exploration, debugging and discovery.
Test as audition. I thought one day Why am I using double-quotes all the time? This is just a C string literal habit. So I tried using single-quotes until I knew the advantages of using double-quotes.
3. Code clearly
Readability is the second issue after function. (Hi, Ovid)
4. # to clarify
If you can't make the code clear, comment to clarify.
5. Gen code
Generate code if possible. Generated code is more consistent, efficient of production, and better planned than ad hoc code. The act of generating code forces a reasonable amount of planning and structure to the process.
It also tends to collect important information in one place. This harks back to Brooks' show me your data ....
6. Doc I/O & intent
Document the input and output and the intent of functions and modules. This is the coder's translation of specifications. These comments should treat the code as a black box.
It's the Perl way and very readable. Occasionally I'm tempted to save space with modernNameStyles so this is high on the list.
perltidy the code, an automatic cleaning may not shine like a hand rubbed polish, but I'm a geek, I believe in automation and I have other things to do.
Also being neat and tidy is a good thing. Well, I've heard that, maybe someday I'll know firsthand.
Double quotes are the right thing to use most of the time. However when generating Perl with Perl, I should use the generic quoting mechanisms more often.
10. need less
Good life advice generally.
To code beyond the current requirements is to ornament your code pointlessly. Some folks think this is slovenliness or shirking. They think you need to anticipate future growth of the code. They tend to waste time building features or infrastructure that is never used or needed.
Code to the current need. Don't make up additional spec's.
Also need fewer modules for your code for distribution. Be quick to use modules, but also consider factoring them out of your code.
Is it time to submit to the CVS repository?
o- Use \s not tmp vars
This is somewhat experimental for me. A post by merlyn has me raising the bar greatly on meaningfulness of variable names. The idea is to use whitespace to format longer expressions instead of using meaningless variables to split large expressions into multiple statements.
o- Catch signals.
Some of what I'm writing should. Often what I write doesn't require this type of robustness, so I'm reminding myself.
o- Document with pod.
I do, but I rely too much on the code and my memory.
o- 2 == $var not $var == 2
An old C-ism put the constant first thereby catching any = instead of == typos.
o- id lgth =~ scope & presence.
Identifier name length is bound to scope and presence.
This is important, but we're getting to things that are second nature for me. Big long names go with large scopes, short names with small scopes. The exception are the pervasive variables that are central to a process and pop up again and again. $_ is the archetypical example. If you want to write $accounts_payable thousands of times fine, I'll just use $ap. This assumes that $ap has to be understood by anyone that has a clue about the codebase.
o- perldoc something!!?
I know this list pretty well, maybe I'd be better off reading a perldoc.
o- flyweight objects!?
I'm ignorant but I plan to check these out sometime.
o- use strict
I always do or this could be number two on the list.
o- use warnings
o- exit with meaning
Like handling signals, I should keep this in mind.
o- No pod & code.
Abigail-II's "don't interleave POD and code" obvious when you think about it. Having used here docs and such I'm not sure that I'd even support a "=begin comment" usage. The ugly hashs flowing down the left gutter sure do differentiate block comments from code.
o- < not >
petral's idea that 0 < $val <= 100 is more natural than 100 >= $val > 0. I think I just do this. But I never thought about it nor have I checked. Nice idea, not too important.
o- don't use select *
I never have. But I never thought about the unruliness of the beast either.
o- don't use one char var names
edited: Wed Dec 11 17:16:34 2002 by jeffa - added readmore tag