develooper Front page | perl.perl5.porters | Postings from November 2010

Re: [PATCH] perlipc.pod Revamp

Thread Previous | Thread Next
Paul Johnson
November 1, 2010 07:48
Re: [PATCH] perlipc.pod Revamp
Message ID:
On Thu, Oct 28, 2010 at 06:18:01PM +0200, Shlomi Fish wrote:

> This is a new version of the patch for revamping perlipc.pod now that the 
> whitespace normalisation patch was committed.

Hello Shlomi,

[ Apologies to all for the length of this post.  If you don't want to
read it all, please skip to section 5 at the bottom. ]

I find myself uneasy with the changes you are proposing in this patch.
I have given the matter a little thought and would like to explain why
that is so.

We have a document describing the way in which contributed modules are
to be managed within the perl core.  This is perlpolicy.pod.  Please
take a moment read this document if you are not familiar with it.  The
relevant section is entitled "CONTRIBUTED MODULES" with the sub-heading
"A Social Contract about Artistic Control".

Although this document does not specifically mention documentation, I
believe that many of the principles defined therein are applicable to
documentation as well as code and perhaps even more so to code within

Writing documentation is hard.  Writing good documentation is even
harder.  With that in mind, I am grateful to anyone to attempts such a
task.  However, one of the problems Perl now faces, in my opinion, is
not a dearth of documentation, but rather an abundance of documents
which are losing cohesion.  Most aspects of the language are documented,
if only you can find the correct location.  This is not a simple problem
to solve, and it gets slightly harder every time someone comes with a
well intentioned and locally useful documentation patch, adding more
details or examples to some section which they had found less than

However, that is not the problem you are trying to solve.  I believe
that you are wanting to modernise the code examples to demonstrate best
practices and (perhaps) to make them into standalone snippets that can
be copied and pasted into users' code.

Whilst this, on the surface, might be considered a laudable goal, I do
have a number of concerns, not specifically about the changes you have
made (although many of them do concern me), but more generally about the
direction in which this takes us.  Let me try to explain some of my

1.  I'm not convinced that we would be able to get a consensus on what
    the best practices are that we would like to promote.  For example,
    I would consider some of the changes you have made to be changes for
    the worse, as would perlstyle, which is probably the closest thing
    we have to a definition here, and which is a fairly relaxed
    document.  We certainly don't want to get anywhere near to edit wars
    over style.

2.  Best practices change over time.  When this document was first
    written it didn't contain anything which, at the time, would have
    been considered bad practice.  (I'm not sure it does even now,
    though I suspect that even Tom would write the code differently
    nowadays.)  This means the we would periodically need to update the
    code in the examples, possibly using constructs recently added to
    the language.  I'm not suggesting this is a particularly difficult
    problem to solve should we want to, I'm more questioning whether we
    want to.

3.  And why should examples in the documents have to demonstrate best
    practices anyway?  The purpose of most examples is not to explain
    how to program Perl in general, but to describe some particular
    aspect of the language.  It could be considered that any extraneous
    code detracts from that goal.  That is why I would consider it
    unnecessary to declare and initialise all the variables used, for
    example.  Similarly, the addition of extra blank lines, which may be
    useful in code itself, could simply prove distracting in a code
    example where it might the more useful to be able to see all the
    code on the same page as the text describing it.

4.  It might even be considered advantageous to have numerous code
    styles sprinkled around the official perl docs.  There are certainly
    numerous Perl styles in the core, in CPAN modules and in the vast
    majority of codebases where more than a couple of people have worked
    on the code.  Why not in the documentation?

5.  My greatest concern, though, is that if someone has gone to the
    effort to write a document, then they should have the right to
    determine the style they will use not only in writing the text, but
    in writing the code examples too.  Obviously if the code is wrong,
    or is rendered incorrect by subsequent changes to the language, then
    it needs to be updated.  Otherwise, I would be wary of making code
    changes and would, in the spirit of perlpolicy.pod, prefer that such
    changes only be made with the blessing of the original author, where
    that is feasible.  In this case I think this should be feasible and,
    if you have such a blessing, then I withdraw all my concerns about
    this particular patch, although my general concerns still stand.

So, in summary, whilst I'm very thankful for the changes you have made
fixing mistakes, I fear that applying the stylistic changes would set a
dangerous precedent.

Paul Johnson -

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About