malaga has asked for the wisdom of the Perl Monks concerning the following question:

i am just finishing up my first 100% perl contract, and with the help of a lot of people on this site, i did very well. i only have one day left, but before i leave the company, i want to go over my scripts and make sure i haven't done anything, (or omitted anything) that i shouldn't have. i want to be sure i've done a professional job. does anyone have or know where to find guidelines for this purpose?

Replies are listed 'Best First'.
Re: clean up/professionalism
by dws (Chancellor) on Feb 13, 2001 at 10:55 UTC
    It looks to me as though you're making a very common "professional" mistake.

    The mistake is this: you've not answered the question "professional to whom?" Instead, you're substituting your own definition, augmented by the opinions of semi-random strangers. Now having a strong sense of professionalism and values is a Very Good Thing, but when you're taking someone else's money, you need to work to their definition. (If you don't agree with and can't abide their definition of "professionalism", don't take the job.)

    It may be a little late in the game for you to ask, but have you determined what the people on the other end of the contract consider to be a "professional job"? If they're big on written doc, focus there. If they're big on unit tests, focus there. You get the idea.

    (Update: On re-read, my tone may be a bit condescending. Not my intent. This particular mistake is one I have lots of first-hand experience with. --dws)

Re: clean up/professionalism
by markjugg (Curate) on Feb 13, 2001 at 08:42 UTC
    I think the big picture for professionalism in coding goes something like this:
    • Clear and Consistent Code Design
    • Documented
    • Secure
    Before I launch a perl project for a client, I add a standard header to all the files, that includes it's name, a short description, a version, and basic info on the license, contact info, and an abbreviated ChangeLog of major changes to the script.

    As for "good style", that's a sort of elusive and fuzzy thing. I enjoyed reading the The Practice of Programming which relates to that topic.

    As for security, I'm sure you can find a webpage on secure perl programming to measure your work against.

    Also, there's nothing like good old peer review to improve code. Perhaps there's a co-worker who would be willing to look things over?


Re: clean up/professionalism
by AgentM (Curate) on Feb 13, 2001 at 08:46 UTC
    The question is rather vague, so all I can offer you are some tips if you want to leave your mark:
    • The code works and has been thoroughly tested under "idiot-mode" ala a divide-by-zero does not sink the ship.
    • The code uses modules where appropriate and runs under the standard diagnostic tools.
    • Excessive debug info (aka print statements) has been removed.
    • Variables are appropriately named.
    • The provided package includes administrative tools where necessary which allows for the extensibility of the application.
    • If needed, the code is appropriately commented.
    • The code has been "idiot-tested".
    • The code has been "idiot-tested".
    • The code has been "idiot-tested".
    Good luck!
    AgentM Systems nor Nasca Enterprises nor Bone::Easy nor Macperl is responsible for the comments made by AgentM. Remember, you can build any logical system with NOR.
Re: clean up/professionalism
by cat2014 (Monk) on Feb 13, 2001 at 10:43 UTC
    You should check that your code fails gracefully, too. That was a really hard one for me to learn- I wrote code that had all kinds of silly dependecies (servers being kept up by other people's personal cron jobs, report files being available in random places, etc), and then forgot about the scripts. When the script would start randomly failing because something it had depended on changed, it would take me forever to track down the problem. I try to be really paranoid now, and wrap stuff in evals, check return codes from system calls, & write error strings that make sense. It's good to not have to explain to people that you have no clue why your tool started failing over weekend & that you'll have to get back to them in a day or two. Although I guess that if you're leaving, you won't have to deal with that part. (:

    It's really hard to make the adjustment from hacking code for your CS homework or your own website to writing code that people depend on to do work, though. I'm always finding new things that I should be doing & becoming embarassed that I hadn't been doing them before. -- cat

      thanks cat! i guess i'll start my own checklist, and i'll add your suggestions to it.
Re: clean up/professionalism
by batmonk (Scribe) on Feb 13, 2001 at 09:00 UTC
    Ask yourself this: if someone handed you a folder containing the source and existing documentation, would you be able to maintain or extend it? In six months? A year? If not, then you're not finished.
Re: clean up/professionalism
by Albannach (Prior) on Feb 13, 2001 at 21:13 UTC
    There are a lot of good comments and tips in this thread for you to apply, not least of which is the one from dws about being fully aware of the client's needs and specifications at all times.

    While it's a bit late for your current job, I'd like to add that all these things should be part of your modus operandi at all times, from before you've got the job (if you don't clearly understand the client you may well not get the work, or you may get it not realizing what you're in for), right through to completion. It is good that you've set aside time at the end, but really this quality control must be incorporated all along.

    I'd like to be able to assign to an luser

Re: clean up/professionalism
by LD2 (Curate) on Feb 13, 2001 at 08:39 UTC
    I'm not sure if there are any guidelines for something like that.. usually make your own checklist. But, you may want to make sure that your code is well commented - so that others that inherit your programs will be able to understand what you're doing. Just sometimes useful - make sure that documentation is complete.
Re: clean up/professionalism
by malaga (Pilgrim) on Feb 13, 2001 at 10:38 UTC
    thanks for the feedback...i'm going to check the security aspect first, then spend the rest of the time documenting. any comments as to common security mistakes would be appreciated. thanks, malaga

      If you can make sure the script runs under taint mode (it isn't just for CGIs!), then you've taken a significant step towards making your script secure. Taint mode (-T on the command or '#!' line) isn't a magic bullet, though. It can stop you from making some subtle mistakes, like using unexamined user input in eval or system (not just system) calls. See perldoc perlsec for more.

      Philosophy can be made out of anything. Or less -- Jerry A. Fodor

Re: clean up/professionalism
by malaga (Pilgrim) on Feb 13, 2001 at 23:04 UTC
    thanks for the criticisms too. i do know the expectations of this employer and i do have a professional opinion of my own (this is my first 100% perl job - not my first job!). i don't have a written checklist list yet, but i am working on one now because I think it's a good place to start for future work. i posted this here to see what i might not have thought of (nothing new came up, but i liked reading about how others think the subject through. and if there were some great checklist in the sky i would certainly want to know about it.) This is one very good resource, even if you are strangers :)
Re: clean up/professionalism
by JSchmitz (Canon) on Feb 13, 2001 at 23:26 UTC
    You might want to run them all with the taint switch
    just to make sure there are no significant security
    issues with any of the code.