> after I posted my series of patches to perlipc.pod , I saw that
> tchrist posted his version, which got accepted immediately. As a
> downside to that, I'll have to restart my work. However, I noticed
> that perlipc.pod still has many perceived issues.
Having real issues is quite distinct from having perceived issues.
In the case of perlipc, all are from the latter set.
> Here is a list of things I noticed:
> * «defined($Config{sig_name}) || die "No sigs?"; »
> Shouldn't it be using "or" instead of "||" or maybe an if?
No, it should not. That conflicts with my own way of speaking
Perl, one which is self-consistent, perfectly safe, and followed
by a good number of core developers, such as Rafael Manfredi.
If you break my style, you break the document. And upon my
style, Damian has said:
And yes, they evince no lack of style.
Not my espoused style, but so many people forget that PBP was--at
its heart--a plea for code to be written in *any* consistent style,
consciously and rationally chosen to meet one's own needs. No-one,
I'm sure, would every accuse you of failing to do that.
If Damian does not condemn me, who are you to do so?
VETO
> *
> <<<
> foreach $name (split(" ", $Config{sig_name})) {
> $signo{$name} = $i;
> $signame[$i] = $name;
> $i++;
> }
> >>>
> "foreach my $name" (Gotta practice what we preach). Furthermore, someone said
> we should recommend using a CPAN module for that instead.
The tone and style of the Perl Documentation as set by Larry and myself is
to omit cluttering declarations from tiny snippets. They otherwise
distract from what the point of what is being illustrated. The exception
is if the point of the snippet is the declaration. Putting in declarations
for every two-bit line of code is madness. Look at perlfunc!
VETO
> * unless (kill(0 => $pid) || $!{EPERM}) {
> warn "$pid looks dead";
> }
> unless and and ||? That's a bit confusing.
I'm sorry you're confused. Me, I find DeMorgan's
Law confusing and therefore avoid its application
wherever possible.
unless I killed it or else I got a permission error
it looks dead
is perfectly clear.
Let's try it your way:
if (!kill(0 => $pid) && !$!{EPERM}) {
warn "$pid it looks dead";
}
See what a mess you've made?
Don't be ridiculous. Making people compute boolean
algebra in their heads through a surfeit of boolean
ops is a recipe for confusion.
VETO
> *
> <<<
> my $ALARM_EXCEPTION = "alarm clock restart";
> eval {
> local $SIG{ALRM} = sub { die $ALARM_EXCEPTION };
> alarm 10;
> flock(FH, 2) # blocking write lock
> || die "cannot flock: $!";
> alarm 0;
> };
> if ($@ && $@ !~ quotemeta($ALARM_EXCEPTION)) { die }
> >>>
> Non-lexical filehandle.
Touch noogies. This is a tiny example. $Did $you $really
$want $more $punctuation? @How %about $we *name $the &function,
$too, Like::
my $throw_up_and_alarm_exception_using_die = sub {
die $ALARM_EXCEPTION;
};
Or better yet, we can name our function:
THROW_UP_AND_ALARM_EXCEPTION_USING_DIE {
die $ALARM_EXCEPTION;
};
Except now you'll likely get yourself in a snit for it not having
enough #$%^W#$$^ marks.
VETO
> *
> <<<
> # system return val is backwards, so && not ||
> #
> $ENV{PATH} .= ":/etc:/usr/etc";
> if ( system("mknod", $path, "p")
> && system("mkfifo", $path) )
> {
> die "mk{nod,fifo} $path failed";
> }
> >>>
> We probably want local $ENV{PATH} here, and can't we expect the
> mkfifo system call to work globally already?
No, we most certainly cannot expect that! I didn't put that code in
there out of imagined problems. I put it in there because if I didn't,
it failed on some of systems I tested it on. Why? Because you cannot
count on the user to have those in his path, that's why.
VETO
As for the local(), I feel that again falls in the needless
category, although not so strongly as my other positions.
> *
> <<<
> chdir(); # go home
> my $FIFO = ".signature";
> while (1) {
> unless (-p $FIFO) {
> unlink $FIFO; # discard any failure, will catch later
> require POSIX; # delayed loading of heavy module
> POSIX::mkfifo($FIFO, 0700)
> || die "can't mkfifo $FIFO: $!";
> }
> # next line blocks till there's a reader
> open (FIFO, "> $FIFO") || die "can't open $FIFO: $!";
> print FIFO "John Smith (smi...@host.org)\n", `fortune -s`;
> close(FIFO) || die "can't close $FIFO: $!";
> sleep 2; # to avoid dup signals
> }
> >>>
> Bareword filehandle,
Cope. VETO.
> and 2-args open
THIS IS A MYTH!
There is nothing whatsoever wrong with using two-argument
open when you have complete control over the content of
those strings and you are not setting the encoding in the
open itself.
VETO.
> and || instead of or.
Broken style. VETO.
> I won't mention
> bareword filehandles again, but the exist in many other places.
VETO
> *
> <<<
> use FileHandle;
> use IPC::Open2;
> $pid = open2(*Reader, *Writer, "cat -un");
> print Writer "stuff\n";
> $got = <Reader>;
> >>>
> We need to make it use strict friendly.
No, we do not. Vide fricking supra.
> *
> <<<
> #!/usr/bin/perl -w
> >>>
> use warnings instead of "-w".
ACK
> *
> <<<
> my ($remote, $port, $iaddr, $paddr, $proto, $line);
> $remote = shift || "localhost";
> $port = shift || 2345; # random port
> if ($port =~ /\D/) { $port = getservbyname($port, "tcp") }
> die "No port" unless $port;
> $iaddr = inet_aton($remote) || die "no host: $remote";
> >>>
> we should declare the variables at first assignment instead of all in one
> place.
What? Three lines away is too far? I think not!
Anyway, that style is optimal for this construct:
my ( $remote, # asdfasdf
$port, # asdfasdf
$iaddr, # asdfasdf
$paddr, # asdfasdf
$proto, # asdfasdf
$line # asdfasdf
);
Are you saying my variable names are so obscure that it needs that
sort of commenting at the point of declaration?
> *
> Shouldn't the example use IO::Socket and friends?
No, do not Bowdlerize working code.
*HOWEVER*
A version or two of things using IO::Socket might reaonable go in there on
top of that--assuming you deem IO::Socket's documentation inadequate.
But to strike away how to do this in the only place it exists in the
documentation is inadvisable in the extreme, so much so that I'm sorely
tempted to use stronger language.
Fortunately, this time I shan't.
> And here's a multithreaded version. It's multithreaded in that
> like most typical servers, it spawns (fork()s) a slave server to
> handle the client request so that the master server can quickly
> go back to service a new client.
> >>>
> The term "multithreaded" is misleading it. It is multi-processed - not
> multithreaded, because it does not use threads.
It was how we talked about things when that code was written. I wrote
plenty of perl4 client-server code, and that's what it was. I believe
the Camel and the Cookbook have notes clarifying the original usage.
I can dig those out if need be.
> *
> <<<
> Section 5 of CPAN's F<modules> file is devoted to "Networking, Device
> Control (modems), and Interprocess Communication", and contains numerous
> unbundled modules numerous networking modules, Chat and Expect operations,
> CGI programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Telnet,
> Threads, and ToolTalk--to name just a few.
> >>>
> We should no longer mention that modules file.
ACK.
> Should I send patches to correct all these issues
I am not going to tell you want to do. But I will say
that I do not believe 97% of your "corrections" have
any merit whatsoever, and in fact suffer from demerits.
> (because the Perl
> documentation should represent the best practices)?
I again direct you to Damian's quote. Your statement
is simple, seductive, and misleading to the point of
being wrong.
> And I hope that this time all my work will not be for
> naught again.
Work on things that need working on, and it won't be.
Work on things that don't need working on, and it may.
Nobody can tell you what to do, but that is my opinion,
and I may be wrong.
--tom
