Pick up The Pragmatic Programmer or Code Complete, and read what they have to say about comments. As long as you expect to have separate documents for the maintainer and the computer, you are doing something wrong. Document the interface, not the code. Make the code its own comment. (Good variable and function names really helps. So do well-written messages in your error checks.)

My second point is references. Don't use references because they are cool - OK I can buy that. But don't go out of your way to avoid nested data structures either. (Which happen to use references.) Gratuitous abuse of references is bad, but so is the gratuitous abuse of virtually any other feature. Why single out references?

Other than those two nits I think you are spot on.

A final point that is too often forgotten. There is nothing wrong with not knowing something. Programming is a field that is constantly changing and you will constantly be dealing with things you don't know. So if you have any questions at all, check the documentation and if you cannot figure it out, start asking questions.

Not knowing is expected. But if you are not learning then you have a problem.

I know this is a very late response to a now-old node, but I want to add that commenting code using #comments is less useful than documenting code using =pod / =cut slices. I just picked up the habit of putting all major information into POD and I'm loving it.

This way my subs (or packages) can sit in fully-documented separate files and if I need to know something I don't have to sort through the code to learn find it, perldoc package_name.pl gets me to the information I need very quickly (this is basically an echo of Tilly's comment about documenting the interface). Storing the libraries as libraries (instead of putting all the code in a single file) during development means that the POD in the packages does not interfere with the POD for the main script-- this also means that I can share my package with others easily, since the docs are already written. Sometimes # is good for short notes, but for longer notes, you can always use POD tag like =note to make notes that don't show up in the normal course of POD parsing.

I actually just started reading the Pragmatic Programmer yesterday (got it from Fatbrain - and that wasn't a plug).

My only issue is with your statement: "Make the code its own comment. "
Since not everyone will use meaningful names when writing their code (I'm certain you have seen it too), I tend to think that comments are important. Now, I didn't mean comment every line - or even every 3rd line. I meant that (and I should probably have said) there should be a decent description for the subroutine and what(sometimes how) it does. After all, why do we have the '#' if we shouldn't use it?

Thanks for the feedback. It's good to know that people are actually reading what I post and taking the time to comment on it. :-)

Mick

philosiphising? does anyone know how to spell that word?

anyway... my first programming teacher taught me that when you're commenting subroutines (or functions or methods) its usually a good idea to put in a 'precondition:' statement and a 'postcondition:' statement. in other words, tell the reader what the subroutine expects to recieve as arguments (including implicit error-checking perhaps) and what the subroutine will spit out as a return value.

jeff

Well put it this way. If humans read a different document from the computer, you have a problem. The fact that there are programmers who do not understand how to code well is their problem. If you rely on such programmers and have put no thought into communicating your requirement that the code have decent quality, then their problem has become yours.

Bad programmers are a hazard to your code-base. So give them feedback and review. Doing that up front saves energy in the end over letting it pass and cleaning up after. A stitch in time and all that.

BTW I do comment most subroutines. Input arguments, brief description, and return. Often only the ones that are meant to be used outside the module though...

All I would like to add is, ALWAYS make your variable names MEANINGFUL.

"cRaZy is co01, but sometimes cRaZy is cRaZy".
                                                      - crazyinsomniac

I agree with all except for the first point. I don't know if references are "cool", but they are an excellent way to pass data around in your program efficiently, as well as a great way to build complicated data structures. (this applies to Perl, not the other languages :)

I've actually seen instances where people have used references just for the sake of using them. I'm sure that using a simple reference to a scalar in the same block is adding more overhead than is necessary.

Don't get me wrong, though. I do understand the usefulness of a reference in such things as nested data structures and for passing data between subs and whatnot. I just object to using one where it's not needed.

Mick

Those are all really good points.

As for modularity of code: despite what I heard about Perl before I started using it (about a year ago), I've been really surprised at how easy it is to come back to a program after a few months of working on other stuff. Using subroutines and using the strict module (as mrmick suggests) really helps.

I know we all love Perl for different reasons. For me, it's the way I found Perl to be very approachable. It wasn't difficult to swallow like C. Plus, it's just plain fun to code in Perl.

-ppm

use Benchmark;

my @big_array = (1 .. 10000);

sub ret_array { return @big_array; }

sub ret_ref { return \@big_array; }

timethese(10000, {
                  'return_array' => sub { my @array = ret_array(); },
                  'return_ref'   => sub { my $array_ref = ret_ref(); }
                });
[download]

Benchmark: timing 10000 iterations of return_array, return_ref...
return_array: 120 wallclock secs (117.82 usr +  1.65 sys = 119.47 CPU)
return_ref:  0 wallclock secs ( 0.03 usr +  0.00 sys =  0.03 CPU)
[download]

/\/\averick

Just a comment on subroutines,
The rule of thumb I follow is if I use the same construct twice, it should be a subroutine

coreolyn Duct tape devotee.

Always check the results of all system calls (put lots of or die's in) - this will save you lots of heartache later!

Personally speaking, for hashes I tend to use references all the time because then your code looks the same everywhere (the place where you created the hash and the place where you passed a reference to it into a subrouting). YMMV of course!