Re: Use PSR coding guidelines in php.net docs (instead of PEAR-CS)

Hi

Den fre. 4. sep. 2020 kl. 17.49 skrev Tymoteusz Motylewski
<[email protected]>:
>
> Hi,
> Right now (as stated here: http://doc.php.net/tutorial/style.php) the code style used in PHP documentation is PEAR-CS https://pear.php.net/manual/en/coding-standards.php
>
> The problem is that:
> - PEAR-CS does not cover new PHP versions (e.g. namespaces are missing)
> - it has a very little adoption
> - it's not maintained
> - the whole PEAR is becoming obsolete

See my inline reply further down. TL;DR the PHP Documentation Team
builds upon the old PEAR-CS, but there is nothing formal written down.

> I suggest that PSR-12 should become the coding standard for PHP docs.
>
> I've created a ticket https://bugs.php.net/bug.php?id=80060
> and got redirected to mailing list
>
> "The PSRs are unofficial community-written guidelines for interoperability between frameworks and projects. If PHP were to follow their guidelines then that could be interpreted as an endorsement - reasoning that extends to other areas, such as why php.net does not employ a popular framework."
>
> I would understand the concern if we were talking about certain commercial product, tool or framework.
> Here we're talking about a standard which:

That standard is however, still a tool.

> - has a broad acceptance in the PHP industry
> - doesn't have an alternative thus became the one standard in the industry
> - its adopted by many tools and framework from the PHP community

While these are solid arguments in their own right, it doesn't
necessarily mean that these merits also apply to the PHP project. Like
mentioned in the bug report, the PHP project must remain neutral. The
moment we adopt the X standard, then it will be seen as favoritism,
"Why does the PHP project use this standard when Y is clearly better?
I better bring my case up for using Y over X". If the PHP project were
to pick X coding standard then possibility for any widespread adoption
for anything else is next to nothing. Userland is free to create
whatever organizations you would wish to and support their course, or
not, in the same way that the PHP project strives to be neutral.

> I agree, and I would love PHP to either set standards, or to endorse existing standards. Because right now you can read this argument that PHP is endorsing obsolete PEAR-CS, which I hope is not true ;)

I think while we base the idea on PEAR, I think the style has slowly
evolved into our own with roots there of. I'm sure some examples out
there in the manual may be compatible with X, Y or Z PHP coding
standards, sometimes not. It is not really the end of the world if
some examples use K&R / Allman indentation style and others use OTBS.

The moment we however open up and decide to invent a new coding
standard, it will have many challenges, such as:
 - Everyone would want to take apart of it, because it is the PHP
project and there seems to be a certain prestige in having had a say
in something that involves the PHP project
 - There is the chance that someone will adapt that and what do we do
then, maintain it or? What if someone forks it and it becomes
widespread, do we then adopt that and break that neutral stance?

The thought of the political process of tabs v spaces, which
indentation style, and naming, would have to be redone. While I don't
speak for everyone, I can't stay that I know of anyone that would be
interested in such, nor do we have the infrastructure for something
like that to happen.

We even have a CODING_STANDARDS.md file in php-src, which is not
respected to the slightest, perhaps because it has not been updated
our "recent" switch to C99, but it is very common to have commits
break the C++ comment style rule for one.

> In general I would like to see more PSR being mentioned in PHP docs, e.g. PSR-4 in https://www.php.net/manual/en/language.oop5.autoload.php

We cannot do this because it creates favoritism, the moment we endorse
X, then Y wants some too and Z, and it will continue like that. That
is why it is very important for the PHP.net project to remain neutral.

> In comparison to other languages it's hard to learn PHP from the official docs, as no tooling or best practices are outlined e.g. I did not find any mention of composer in the docs.

The PHP manual is primarily a reference guide, it is not written as a
tutorial. There was a point some 10+ years ago where it was proposed
but it never manifested, and to be fair. At this point there are so
many other resources on the web which come and go all the time, if we
were to link to some, then again it creates a favoritism and it will
also become a maintenance burden as the links might change. We are
already fairly bad at the latter part.

-- 
regards,

Kalle Sommer Nielsen
[email protected]