On Wed, Jun 17, 2009 at 08:24, Steve Bertrand<st...@ibctech.ca> wrote:
> Hi all,
>
> One of the things that came out of my last thread was my lack of
> documentation, so now I'm keeping the documentation up-to-date as I make
> code changes.
>
> I'm trying to come up with a decent layout for this. Tentatively, it
> looks like [1]. Does this appear to be acceptable? Could you recommend a
> perldoc or two in a style that you prefer for ideas?
Rather than providing an EXAMPLES section (which is what the SYNOPSIS
section is for), you should be providing a METHODS section that looks
like this:
=head1 METHODS
=head2 new
Creates a new EagleUser::Ledger object, returns undef if an object
cannot be created
=cut
#FIXME: probably should be using a payment object rather than a
straight hashref,
#that would also fix the fact that the values of the keys are not defined here
#(since they would be defined in the pod for that class)
=head2 gledger_add(EagleUser, PAYMENTS)
Adds a list of payments to the ledger for a given EagleUser object. PAYMENTS
is an a list of payments. Each payment should be a hash reference containing
the keys payment_method, quantity, item_name, gst, and pst.
Since the other methods are not public, they should not be documented
here. Their names should also start with an _ as visual sign that
they should not be called by other code.
snip
> Are there any tricks you use (mental or code-wise) to help you down the
> road to prevent API changes, particularly on how you accept/name input
> parameters?
snip
Other than keeping docs updated and rereading them when designing new stuff, no.
snip
> One more thing, regarding those who prefer to code within the 72 column
> boundary...can you provide a couple of short examples as to your
> preferred indenting/wrapping format style when the need to wrap long
> lines of code?
snip
I wrap at natural breaks such as operators (comma, +, ||, etc). If a
string is too long I break it at a whitespace character and use the
either commas (with things like print or die that accept lists) or the
concatenation operator. When I wrap a line I indent it one indent
level. If I have a complex logical statement I break it into chunks.
if (
$this eq $that or
$foo == $bar or
$string =~ /something good/
) {
print "this line in is ",
"too long to fit\n";
my $x = $count * $size /
$expected_size;
}
But the most important thing to remember about wrapping code is that
if you are hitting the 72ish character limit something is probably
wrong with your code. You should avoid having more than three levels
of nesting in a function, and given eight character tabs that leaves
you 48 characters in the worst case (assuming a 72 character limit, I
tend to use a soft 72 character limit, with a harder 80 character, but
I let the occasional long string go past 80 characters). If you need
to write an expression longer than 48 characters it is probably a good
idea to add some vertical whitespace to it even if you aren't hitting
the edge of the screen (for instance, the if statement above should be
written in a similar style regardless of how long the line is). If
you find yourself using more than three levels of nesting, it is time
to take a good look at the structure of your code. Many times people
will say things like
sub foo {
if ($thing) {
#do something
} else {
#do something else
}
}
when the should say
sub foo {
if ($thing) {
#do something
return;
}
#do something else
}
or
sub foo {
unless ($thing) {
#do something else
return;
}
#do something
}
Which of the two forms you choose should be based on length of code.
The shorter item should be in the if/unless. In many cases there
isn't even an else, the code looks like
sub foo {
if ($thing) {
#do somehting
}
}
in these cases it is better to exit early:
sub foo {
return unless $thing;
#do something
}
All of this holds true for loops as well (except you use next or last
instead of return).
Another good way of cutting down the length of a line is to start
looking for things that should be functions rather than straight code.
snip
> ** My wild use of references is solely so I can drill in their proper
> use/syntax
snip
Unfortunately, part of learning to use something is learning when to
use it. If this code is going to be used in production you should not
be playing with references just to play with them. Leave that to toy
programs you write for yourself.
--
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.
--
To unsubscribe, e-mail: beginners-unsubscr...@perl.org
For additional commands, e-mail: beginners-h...@perl.org
http://learn.perl.org/
