Re: IYHO, what do you consider good code?

[theorbtwo]

Some things that I consider "best pratices":

• Always use strict; and use warnings; (or -w if you're using perl <5.6). If you do somthing that breaks a warning or stricture, use a no that lets you brake just that one, and in the tightest scope possible.
• Write your code to be reusable.
• Write your code to handle at least twice the biggest dataset you expect to ever be handed to it.
• Expect the project to become more complicated as you are working on it.
• If you think of somthing while writing that you could do better, but don't have time to do it that way, comment.
• Comment on input and output of subs at the top of the sub. If the input is a file containing data in a format, comment on it.
• If you write somthing one way, and then have to go back to it to fix a subtle problem, comment on it, because otherwise you may be tempted to go back later, and end up changeing it back to exactly what it was before.

Note that best pratices are different when you're writing code for different purposes. I generaly exepect to be the only one who needs to follow my code; that's the environment I work in. Similarly, most of my code is throwaway. That doesn't mean I don't code in reusable subs -- I often find that also makes my code easier to change later when I have to make it do more later. To answer the question posed in the subject, though, which is different: I consider good code to be code that is produced that does what it needs to do, was produced within schedule and budget, and is readable and work-with-able by the people who need to work with it. Note that I say "what it needs to do", not "what it was spec'd to have to do".

---

Warning: Unless otherwise stated, code is untested. Do not use without understanding. Code is posted in the hopes it is useful, but without warranty. All copyrights are relinquished into the public domain unless otherwise stated. I am not an angel. I am capable of error, and err on a fairly regular basis. If I made a mistake, please let me know (such as by replying to this node).

[halley]

A couple of my tips on style, regardless of language.

Strategy in comments, tactics in code. Don't explain every statement or operator, but explain the goal of the following few statements or chunk of code. Another suggestion is to write the comments first as you're thinking about what you want to get done, then "translate" the intent into implementation. Don't write clever code which needs explaining-- just accomplish the tactics simply and directly.

There are only three numbers in Computer Science. Zero, One and N. Zero refers to the complete lack of something: no variable, no method, no capability, no support. One refers to a sole solution: one variable, one method, my way or the highway. N represents an arbitrary scalability, an array which can grow, a method reference, a parameterized technique with room to expand. If you find a need for two, structure your code so it can handle three, four or more. That goes for allocations, methods, strategies, resources, resource types, everything.

--
[ e d @ h a l l e y . c c ]

[DrHyde]

There are only three numbers in Computer Science. Zero, One and N

Someone suggested on the london.pm mailing list some time ago that if you ever use a constant other than 0 or 1 you should comment why. I can see his point, although I make exceptions for well-known scaling factors like 7, 24, 60, 3600 and 86400 when mangling times and so on. I also don't bother documenting the constants when I do something like:

$foo = ($foo & 112) >> 4;

although that gets wrapped up in a little subroutine whose function is documented, including a pointer to the relevant standard. But just about every other constant I do inded comment. eg, from my current project ...

$price /= 100; # convert from pence to pounds
...
$time += 23 * 3600 # because we're changing timezone

[webfiend]

I agree with most of this, and do my best to follow it in my own code. Lately, though, I have been softening up on the use strict dogma. It's a great idea for you and me, but it might make some more unusual constructions more difficult. Good testing support provides a lot of the same usefulness as strict, but without the compiler errors :-). If your code changes an assumption, then the tests that rely on that assumption will scream bloody murder.

So here is my slightly modified version of the first point:

• Always use strict and use warnings unless you know exactly why you aren't using them, and comment on exactly why you don't.

Update: theorbtwo's qualifier made perfect sense to me. Can't imagine why I forgot it. Whatever, the qualifier is now applied :-)

[DrHyde]

I'd say always use strict and warnings. Only turn it off for the sections of code where you need to. If you do think that you need to, consider whether there's a better way of doing the job - there almost always is. You generally only need to turn them off when you're expecting something magical to happen or are doing something Just Plain Weird. Magic and Weirdness are hard to read and so hard to maintain. Even with sufficient comments, someone who has to maintain your code later might just have to rip it out and start again if you try to be too clever. And, as well as commenting the input and output of your subroutines, COMMENT YOUR ALGORITHMS. (added shouty bit later)

[theorbtwo]

I could agree with that, if you put a ..."and comment on exactly why you don't". However, note that I specificly didn't say that every line of code must comply with every stricture and warning.

---

Warning: Unless otherwise stated, code is untested. Do not use without understanding. Code is posted in the hopes it is useful, but without warranty. All copyrights are relinquished into the public domain unless otherwise stated. I am not an angel. I am capable of error, and err on a fairly regular basis. If I made a mistake, please let me know (such as by replying to this node).

[diotalevi]

I find myself using strict less and less often but only in constrained circumstances. Small scripts, stub applications for CGI::Application, that sort of thing. If it fills half the screen its probably too long to write without strict. Maybe this just means a lot of my scripts are now less than half a page long, I'm not sure. I just know that it is occasionally easier to just throw caution to the wind. But then I am also very likely to make warnings fatal which for me is a stricter sort of strict - your code ends being *required* to operate on the data sanely or you fall over a fatal runtime error.

---

Added text. I included an example of the sort of thing I'm thinking of. This could be written with strict but why bother? I also wrote Re: and another without strict or warnings. I added them on at the end just to keep the 'use strict'/warnings people happy.

#!/usr/bin/perl -T
BEGIN { $root = '/users/greentechnologist.org'; }
use lib $root;
use Camp;
Camp::DataEntry
    ->new( TMPL_PATH => "$root/Tmpl/",
           PARAMS => { DBH_DSN => 'dbi:Pg:dbname=...',
                       DBH_USER => '...',
                       DBH_PASS => '...',
                       DBH_OPT  => { RaiseError => 1 } } )
    ->run;