Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask

comment on

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

2. Test

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.

7. use_names_like_this

It's the Perl way and very readable. Occasionally I'm tempted to save space with modernNameStyles so this is high on the list.

8. tidy

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.

9. q

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.

o- ci

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

In reply to A guide to coding Perl by rir

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

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?

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

    How do I use this? | Other CB clients
    Other Users?
    Others meditating upon the Monastery: (5)
    As of 2019-12-10 02:11 GMT
    Find Nodes?
      Voting Booth?

      No recent polls found