RE: My philosophy on coding (in Perl and other languages):
by tilly (Archbishop) on Aug 12, 2000 at 20:08 UTC
|
What do you mean by "document the hell out of your
subroutines"?
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. | [reply] |
|
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.
| [reply] [d/l] |
|
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
| [reply] |
|
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
| [reply] |
|
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...
| [reply] |
(crazyinsomniac) RE: My philosophy on coding (in Perl and other languages):
by crazyinsomniac (Prior) on Aug 12, 2000 at 11:28 UTC
|
All excellent points.
All I would like to add is, ALWAYS make your variable names MEANINGFUL.
"cRaZy is co01, but sometimes cRaZy is cRaZy".
- crazyinsomniac | [reply] |
RE: My philosophy on coding (in Perl and other languages):
by turnstep (Parson) on Aug 12, 2000 at 04:33 UTC
|
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 :)
| [reply] |
|
| [reply] |
RE: My philosophy on coding (in Perl and other languages):
by PotPieMan (Hermit) on Aug 12, 2000 at 08:23 UTC
|
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
| [reply] |
RE: My philosophy on coding (in Perl and other languages):
by maverick (Curate) on Aug 14, 2000 at 18:48 UTC
|
I agree with all your points with a slight rephrasing
to the first point. How about 'use references when they
are the best solution to the problem'. Consider the
following benchmark.
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(); }
});
Which yeilds:
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)
Returning the reference is faster since it doesn't have to
copy each element, allocate memory for it, etc. Granted
it can make your code more cryptic, but in the cases where
the returned array is large, or the subroutine is called
often, the speed increase is well worth it.
/\/\averick | [reply] [d/l] [select] |
RE: My philosophy on coding (in Perl and other languages):
by coreolyn (Parson) on Aug 12, 2000 at 17:34 UTC
|
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. | [reply] |
RE: My philosophy on coding (in Perl and other languages):
by ncw (Friar) on Aug 14, 2000 at 13:54 UTC
|
I would add :-
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! | [reply] |