R. Joseph Newton said:
> Paul Kraus wrote:
>
>> Reading through the doc's it says that it is preferred that you write
>> the -h help info using POD. How is this down? Any links on how to write
>> pod or have a perl script display pod for built in help.
I think someone's already mentioned Pod::Usage. The idea behind this is
that you don't have to duplicate your documentation in usage messages,
since we all know that duplication is wrong and needs to be abstracted
away.
>> Do you guys really use POD to document your apps instead of #comments?
The two serve different purposes. You'll probably want to use both.
> IMHO, comments should be few and far between. They break up the visual
> flow of the code, which should reflect the execution logic. Far to better
> to exercise care in selecting identifiers. Perl has allows identifiers to
> be as long as needed to serve the purpose, and well-written code can
> simply tell you in english what it is doing:
I agree with this in principle. Good code can tell you what it is doing,
but what it can't tell you is why. Thus, code clearly and use comments to
explain why this code is needed in the first place. These comments can
often be placed so they don't break up the visual flow of the code.
> sub get_root_classes {
> my $self = shift;
>
> my @root_classes;
> my @unresolved_classes;
>
> foreach (keys $self->{'Classes'}) {
> if ($_->{'parent'}) {
> push $_, @unresolved_classes;
> } else {
> push $_, @root_classes;
> }
> }
>
> return [EMAIL PROTECTED], [EMAIL PROTECTED];
> }
>
> Feedback? Is the above terribly mysterious about what it does? Does it
> really requie comments to elucidate?
I think it needs something, possibly fewer syntax errors ;-)
I presume this is code that you have just made up on the spot rather than
something taken from a working project, but I couldn't say for sure what
the Classes hash was doing. Here's how I would code something similar for
myself or on a team of experienced Perl programmers. I don't expect
everyone to agree with everything. In particular, I expect most people
would be happier with an explicit return statement.
sub get_class_types
{
my $self = shift;
my $roots = [];
my $unresolved = [];
while (my ($class, $props) = each %{$self->{classes}})
{
push @{$props->{parent} ? $unresolved : $roots}, $class;
}
($roots, $unresolved)
}
--
Paul Johnson - [EMAIL PROTECTED]
http://www.pjcj.net
--
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
