[22368] in Perl-Users-Digest
Perl-Users Digest, Issue: 4589 Volume: 10
daemon@ATHENA.MIT.EDU (Perl-Users Digest)
Wed Feb 19 21:10:33 2003
Date: Wed, 19 Feb 2003 18:10:10 -0800 (PST)
From: Perl-Users Digest <Perl-Users-Request@ruby.OCE.ORST.EDU>
To: Perl-Users@ruby.OCE.ORST.EDU (Perl-Users Digest)
Perl-Users Digest Wed, 19 Feb 2003 Volume: 10 Number: 4589
Today's topics:
Re: Religious question: commenting <mr@sandman.net>
Re: Religious question: commenting <abigail@abigail.nl>
Re: Religious question: commenting <tassilo.parseval@post.rwth-aachen.de>
Re: Religious question: commenting <tassilo.parseval@post.rwth-aachen.de>
Re: Religious question: commenting <tore@aursand.no>
Re: Removing HTML tags. <s.patterson@freeuk.com>
Re: Subroutine does not 'see' parameter passed to it (george)
using expect is not working <cb@sebaw.com>
using tar.bz2 (samphdauto)
Re: using tar.bz2 <tony_curtis32@yahoo.com>
Digest Administrivia (Last modified: 6 Apr 01) (Perl-Users-Digest Admin)
----------------------------------------------------------------------
Date: Thu, 20 Feb 2003 00:11:17 +0100
From: Sandman <mr@sandman.net>
Subject: Re: Religious question: commenting
Message-Id: <mr-DE02C0.00111720022003@news.fu-berlin.de>
In article <b3123v$8ce$2@nets3.rz.RWTH-Aachen.DE>,
"Tassilo v. Parseval" <tassilo.parseval@post.rwth-aachen.de> wrote:
> > I was hoping for a reply concerning -style- of commenting rather than
> > amount of commenting (even though amount could be considered a style).
> > I snipped all the parts of your post that had nothing to do with
> > commenting.
>
> But I hope you read them nonetheless. It has nothing to do with vanity
> on my side. I also got some confirmation in what I wrote by Tad's
> posting. Save for the wording, he seemed to point out the very same
> things as I did. Better try to understand these parts. They were
> probably more important than stylistic issues with comments.
The code was "translated" from php. I was only interested in the comments.
> > But you're right of course, the more complex the code is, the more
> > comments should it require. But I tend to comment more than less, just for
> > the purpose of the next guy, since I know what a total pain it is to try
> > to take apart someone elses perlscript to try to find out what it is he's
> > doing.
>
> It's not the amount, it's the content. Redundant comments do more harm than
> benefit since they distract the reader. Use comments to let them stand out
> and point the reader of your code to the essential bits. As said before: the
> 'why' and not the 'what' should be explained.
I partly agree. I think redudant commenting is good in many cases. Take this
for example:
if ($in{who}){ $who = $in{who}; } # default is $in{who}
if ($in{name}){ $who = $in{name}; } # but $in{name} overwrites
if ($in{person}){ $who = $in{person}; } # as does $in{person}
These comments are redundant, since the code clearly shows that this is what
happens. But when these three lines are found in the middle of a lengthy
script, another reader might ask "Why is he doing this? Is this his intention?
All it does is overwrite the variable..." - That reader sees, by reading the
comment, that that is indeed my intention. Or what if I have a foreach() like
this:
foreach (keys %fields){
print "$field{$_}<br>\n";
push @values, $_; # save for later in array
}
The above @values array may only be used this one time in the entire program,
but the comment illustrates how I've imagined that this information might come
in handy, so I put it in an array. And people will know that I did so
intentionally.
--
Sandman[.net]
------------------------------
Date: 19 Feb 2003 23:20:38 GMT
From: Abigail <abigail@abigail.nl>
Subject: Re: Religious question: commenting
Message-Id: <slrnb584a6.1ea.abigail@alexandra.abigail.nl>
Tassilo v. Parseval (tassilo.parseval@post.rwth-aachen.de) wrote on
MMMCDLIX September MCMXCIII in <URL:news:b3123u$8ce$1@nets3.rz.RWTH-Aachen.DE>:
[]
[] Then change your editor. Anyway, using POD (see 'perldoc perlpod') is
[] actually a good idea for the per-function comment. Modules available
[] from CPAN are in fact documented that way.
I disagree. POD is not a substitute for comments. POD is used to create
*user* [1] documentation. Comments are there for the (maintainance)
programmer. The user documentation should describe the interface, which
typically isn't all the function in a module. Private functions shouldn't
appear in the POD - then they aren't private anymore. Information vital
for the programmer (for instance, what kind of algorithm is being used,
internal datastructures, etc) has no relevance to the user. But it will
show up to the user if you use POD to document your functions. Also, one
often doesn't want to explain the functions to the user in the same order
as they happen to appear in the source file. But POD will do that for
you. Furthermore, there's lot of things you might want to explain to
the user, examples for instance, comparisons with other functions,
that are of no interest to the maintainance programmer. Finally, source
files that have POD and code mixed are a nightmare to find your way
around in.
I'd say, POD is a very bad substitute for comments. Keep POD where it
belongs: after __END__.
[1] For modules, the "user" very well might be a programmer. But not
the programmer of the functions.
Abigail
--
perl -we '$_ = q ?4a75737420616e6f74686572205065726c204861636b65720as?;??;
for (??;(??)x??;??)
{??;s;(..)s?;qq ?print chr 0x$1 and \161 ss?;excess;??}'
------------------------------
Date: 19 Feb 2003 23:26:36 GMT
From: "Tassilo v. Parseval" <tassilo.parseval@post.rwth-aachen.de>
Subject: Re: Religious question: commenting
Message-Id: <b313rc$9la$1@nets3.rz.RWTH-Aachen.DE>
Also sprach Sandman:
> In article <b3123v$8ce$2@nets3.rz.RWTH-Aachen.DE>,
> "Tassilo v. Parseval" <tassilo.parseval@post.rwth-aachen.de> wrote:
>> It's not the amount, it's the content. Redundant comments do more harm than
>> benefit since they distract the reader. Use comments to let them stand out
>> and point the reader of your code to the essential bits. As said before: the
>> 'why' and not the 'what' should be explained.
>
> I partly agree. I think redudant commenting is good in many cases. Take this
> for example:
>
> if ($in{who}){ $who = $in{who}; } # default is $in{who}
> if ($in{name}){ $who = $in{name}; } # but $in{name} overwrites
> if ($in{person}){ $who = $in{person}; } # as does $in{person}
>
> These comments are redundant, since the code clearly shows that this
> is what happens. But when these three lines are found in the middle of
> a lengthy script, another reader might ask "Why is he doing this? Is
> this his intention? All it does is overwrite the variable..." - That
> reader sees, by reading the comment, that that is indeed my intention.
The above code should have never been written. A good example how clear
code can make comments obsolete. Typically the above would change to:
$who ||= $in{person} || $in{name} || $in{who};
After all, this is what the ||= and || operators are for. Only a little
familiarity with those is needed to understand immediately what's going
on whereas I find the above if-chain harder to follow (the comment wont
necessarily turn it into nice code).
> Or what if I have a foreach() like this:
>
> foreach (keys %fields){
> print "$field{$_}<br>\n";
> push @values, $_; # save for later in array
> }
>
> The above @values array may only be used this one time in the entire
> program, but the comment illustrates how I've imagined that this
> information might come in handy, so I put it in an array. And people
> will know that I did so intentionally.
I strongly suggest you remove code that doesn't do anything. If I see
the above loop along with the comment I would start searching for the
spot where @values is used since I would read the comment as "this is
stored for usage later in this program"...not later in a development
stage.
Don't you think it's more effective if you focus on the style of your
code instead of comments? I think your code can be squeezed by quite an
amount by even making it more readable. For instance, the "saving for
later" part in your for-loop is suspect. Why not keep %fields around and
whenever you need it later write 'keys %fields' instead of '@values'?
Also, did you realize the strange naming of your variable? You push the
keys of the hash into an array called @values. Now, that would give me
something to think about and rather requires a comment why keys suddenly
become values.
Tassilo
--
$_=q#",}])!JAPH!qq(tsuJ[{@"tnirp}3..0}_$;//::niam/s~=)]3[))_$-3(rellac(=_$({
pam{rekcahbus})(rekcah{lrePbus})(lreP{rehtonabus})!JAPH!qq(rehtona{tsuJbus#;
$_=reverse,s+(?<=sub).+q#q!'"qq.\t$&."'!#+sexisexiixesixeseg;y~\n~~dddd;eval
------------------------------
Date: 19 Feb 2003 23:51:33 GMT
From: "Tassilo v. Parseval" <tassilo.parseval@post.rwth-aachen.de>
Subject: Re: Religious question: commenting
Message-Id: <b315a5$amu$1@nets3.rz.RWTH-Aachen.DE>
Also sprach Abigail:
> Tassilo v. Parseval (tassilo.parseval@post.rwth-aachen.de) wrote on
> MMMCDLIX September MCMXCIII in <URL:news:b3123u$8ce$1@nets3.rz.RWTH-Aachen.DE>:
> []
> [] Then change your editor. Anyway, using POD (see 'perldoc perlpod') is
> [] actually a good idea for the per-function comment. Modules available
> [] from CPAN are in fact documented that way.
>
> I disagree. POD is not a substitute for comments. POD is used to create
> *user* [1] documentation. Comments are there for the (maintainance)
> programmer. The user documentation should describe the interface, which
> typically isn't all the function in a module.
Quite right. But with "per-function comment" I was referring to exactly
that. The OP was sort of documenting the interface of a function
therefore it's a good candidate for POD.
> Private functions shouldn't appear in the POD - then they aren't
> private anymore. Information vital for the programmer (for instance,
> what kind of algorithm is being used, internal datastructures, etc)
> has no relevance to the user. But it will show up to the user if you
> use POD to document your functions.
But it takes very little imagination to come up with a solution that
satisfies these requirements. Simply split the comment into a public
(read: API) part and one that explains how it works. The first is POD
the latter an ordinary comment:
=item B<function( arg1, arg2 )>
C<function> does this and that...arg1 is etc....Returns whatever.
=cut
sub function {
# ++++++++++++++++++++++++
# Describe algorithm or so
# ++++++++++++++++++++++++
...
}
Private functions, well, they necessarily show up in the docs as well
and therefore in none of my modules I used POD for them.
On the other hand, a private function could be commented with POD
nonetheless:
=for __priv private_function( arg1, arg2, ... )>
Description
=end
The standard pod-tools ignore =for directives but you could later make
your own parser that does something special with them if you have use
for it.
> Also, one often doesn't want to explain the functions to the user in
> the same order as they happen to appear in the source file. But POD
> will do that for you. Furthermore, there's lot of things you might
> want to explain to the user, examples for instance, comparisons with
> other functions, that are of no interest to the maintainance
> programmer.
That's why I suggested to split these parts into POD and comment. At
least for my setup your arguments wont stand because my editor (vim)
uses different colors for POD and comments. So when I see something red,
it is POD and therefore meant for the user and when it is greenish it is
a comment meant for internal use.
> Finally, source files that have POD and code mixed are a nightmare to
> find your way around in.
I'd say it's quite the opposite for me. It all visually stands out very
nicely.
> I'd say, POD is a very bad substitute for comments. Keep POD where it
> belongs: after __END__.
Who says they belong there? Perl, the interpreter, knows how to
differentiate between code and POD so obviously it was designed with
this kind of mixture in mind.
Other languages do the same: Java with javadoc for instance or doxygen
as commonly used with C++ (albeit embedded into regular comments each
time).
> [1] For modules, the "user" very well might be a programmer. But not
> the programmer of the functions.
But the programmer of a module is using it at the same time. You don't
only call private functions/methods in a module. Sometimes one public
method calls another public method and there we go: You suddenly need
the "end-users"-view.
But, alas, we don't have to come to an agreement here. As the OP put
into the subject quite rightly: It's religious. Trying to convince me
that your religion is better than mine (or vice versa) is futile. :-)
Tassilo
--
$_=q#",}])!JAPH!qq(tsuJ[{@"tnirp}3..0}_$;//::niam/s~=)]3[))_$-3(rellac(=_$({
pam{rekcahbus})(rekcah{lrePbus})(lreP{rehtonabus})!JAPH!qq(rehtona{tsuJbus#;
$_=reverse,s+(?<=sub).+q#q!'"qq.\t$&."'!#+sexisexiixesixeseg;y~\n~~dddd;eval
------------------------------
Date: Thu, 20 Feb 2003 01:23:48 +0100
From: "Tore Aursand" <tore@aursand.no>
Subject: Re: Religious question: commenting
Message-Id: <pan.2003.02.20.00.19.10.373097@aursand.no>
On Wed, 19 Feb 2003 16:08:30 -0600, Tad McClellan wrote:
> Comments should say _why_ something is being done.
Oh? My comments always say what _really_ should have happened. :)
--
Tore Aursand - tore@aursand.no - http://www.aursand.no/
------------------------------
Date: 19 Feb 2003 23:10:54 GMT
From: Stephen Patterson <s.patterson@freeuk.com>
Subject: Re: Removing HTML tags.
Message-Id: <slrnb583nu.p6.s.patterson@bloodnok.localdomain>
On 19 Feb 2003 00:09:29 GMT, Abigail wrote:
>:) Funnily enough, I'm having a little trouble writing a perl script. I am
>:) attempting to strip the html out of my string.
SGML::StripParser and see the example code for stripsgml
--
Stephen Patterson http://www.lexx.uklinux.net http://patter.mine.nu
steve@SPAM.lexx.uklinux.net remove SPAM to reply
Linux Counter No: 142831 GPG Public key: 252B8B37
Last one down the pub's an MCSE
------------------------------
Date: 19 Feb 2003 17:53:05 -0800
From: georgem@crystalgraphics.com (george)
Subject: Re: Subroutine does not 'see' parameter passed to it
Message-Id: <620c2f02.0302191753.4e9d22de@posting.google.com>
Gunnar Hjalmarsson <noreply@gunnar.cc> wrote in message news:<mQy4a.704$ID6.2139@newsc.telia.net>...
> george wrote:
> > sub writeTrackRecord;
> > {
> >
> > my $somevar = shift;
> >
> > ... does some stuff, and calls some other
> > ... subroutines that are defined in this module.
> > }
> > ...
> > Also, another very strange thing, is that in order for the subroutine
> > to work, I need to put a ';' at the end of the subroutine name in the
> > definition:
>
> With that semicolon, you just declare a subroutine name with the line
> 'sub writeTrackRecord;'. The following block is then *not* part of the
> subroutine, but just a separate block.
>
> Thanks for your response. There was no error message. Without the semicolon, no record was written to the database. With the semicolon, then a record was written to the database -- so that is how I know that the subroutine was evolked.
-- George
> > But when I later removed [the semicolon], the subroutine
> > would not work at all.
>
> Can you be more precise? Exactly what did or did not happen? Which error
> messages did Perl give you (assuming that you are using strictures and
> warnings...)?
>
> / Gunnar
------------------------------
Date: Wed, 19 Feb 2003 23:46:27 GMT
From: "Dartnagnan" <cb@sebaw.com>
Subject: using expect is not working
Message-Id: <nHU4a.776173$zx5.118600@news.easynews.com>
I am stumped as to what to do. My true need is to dynamically pass grab the
contents of a directory decrypt the ones that need to be decrypted and name
them after their original format minus the pgp.
I have tried using Perl's GPG but that doesn't work
I have tried using Crypt::GPG but that doesn't work.
I have tried using system(); but there's no way to pass the passphrase.
Now I am trying to use expect. It's close but still failing. here's what I
got.
my $home="/home/somedirectory";
opendir(DH,$home) || die "Couldn't open the current directory:$!";
while ($_ = readdir(DH)){
next if $_ eq "." or $_ eq "..";
my @test = $_,;
my $test;
for $test(@test){
my $file = $test;
substr($file, -4) = "";
my $pass = "password";
$command = Expect -> spawn ("gpg --output $home/$file -d $home/$test");
$command -> expect(10, "Enter passphrase:");
print $pass."\n\r";
}
}
Any help would be appreciated.
------------------------------
Date: 19 Feb 2003 16:10:26 -0800
From: samj@eisa.net.au (samphdauto)
Subject: using tar.bz2
Message-Id: <65050d4c.0302191610.7583777c@posting.google.com>
Hello all
I am having hard time understanding what is going on with this..
I got Perl source code then got a C compiler gcc-3.2.2.tar.bz2 to
compile it then I got a ziping software bzip2-102-x86-win32 to unzip
the compiler then I don't know how to use this bzip2-102-x86-win32
thing.. it is not an *.exe .. I am working under W2K and my mind is
not set up for open source and all those things yet. I got Programming
Perl which seems to dive right into things with out much intro.
thanks
Sam
------------------------------
Date: Wed, 19 Feb 2003 18:12:51 -0600
From: Tony Curtis <tony_curtis32@yahoo.com>
Subject: Re: using tar.bz2
Message-Id: <87isvf3j3w.fsf@limey.hpcc.uh.edu>
>> On 19 Feb 2003 16:10:26 -0800,
>> samj@eisa.net.au (samphdauto) said:
> Hello all I am having hard time understanding what is
> going on with this.. I got Perl source code then got a
> C compiler gcc-3.2.2.tar.bz2 to compile it then I got a
> ziping software bzip2-102-x86-win32 to unzip the
> compiler then I don't know how to use this
> bzip2-102-x86-win32 thing.. it is not an *.exe .. I am
> working under W2K and my mind is not set up for open
> source and all those things yet. I got Programming Perl
> which seems to dive right into things with out much
> intro.
You've posted this question before.
It's still got nothing to do with perl.
hth
t
------------------------------
Date: 6 Apr 2001 21:33:47 GMT (Last modified)
From: Perl-Users-Request@ruby.oce.orst.edu (Perl-Users-Digest Admin)
Subject: Digest Administrivia (Last modified: 6 Apr 01)
Message-Id: <null>
Administrivia:
The Perl-Users Digest is a retransmission of the USENET newsgroup
comp.lang.perl.misc. For subscription or unsubscription requests, send
the single line:
subscribe perl-users
or:
unsubscribe perl-users
to almanac@ruby.oce.orst.edu.
To submit articles to comp.lang.perl.announce, send your article to
clpa@perl.com.
To request back copies (available for a week or so), send your request
to almanac@ruby.oce.orst.edu with the command "send perl-users x.y",
where x is the volume number and y is the issue number.
For other requests pertaining to the digest, send mail to
perl-users-request@ruby.oce.orst.edu. Do not waste your time or mine
sending perl questions to the -request address, I don't have time to
answer them even if I did know the answer.
------------------------------
End of Perl-Users Digest V10 Issue 4589
***************************************
