Front page | perl.perl5.porters |
Postings from November 2010
Re: [PATCH] perlipc.pod Revamp
Thread Previous
|
Thread Next
From:
Paul Johnson
Date:
November 1, 2010 07:48
Subject:
Re: [PATCH] perlipc.pod Revamp
Message ID:
20101101144750.GX11039@pjcj.net
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
documentation.
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
clear.
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
concerns.
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 - paul@pjcj.net
http://www.pjcj.net
Thread Previous
|
Thread Next