Fix/improve the repo's title and description

[azaozz]

This repository's name "WordPress Coding Standards" is quite confusing and even may be considered a bit misleading. The actual WordPress PHP, JS, and CSS coding standards are in the WordPress Coding Standards Handbook.

I'm guessing this came from WPCS that seems to follow the naming of PHPCS. A better name would probably have been something more descriptive, perhaps WPPHPCS.

Not sure if WPCS (as used on cli) can be changed now. Seems quite a bit of trouble. Also not sure if the repository should be renamed. Again, quite a bit of trouble. But at least there can be a better, non-confusing title (as displayed on the front page), and a better description.

The "WordPress Coding Standards for PHP_CodeSniffer" title is still pretty confusing and a bit misleading. Perhaps something like "WordPress Extensions for PHP_CodeSniffer" or "Extended WordPress Rules for PHP_CodeSniffer" would be a lot more appropriate.

Also

It ensures code quality and adherence to coding conventions, especially the official WordPress Coding Standards.

seems to need a bit more. The term "coding conventions" refers to: "a set of guidelines for a specific programming language that recommend programming style, practices, and methods for each aspect of a program written in that language.". CodeSniffers are not "guidelines" and cannot recommend "coding practices and methods", i.e. code architecture, code layout, where to use classes and what type(s), etc. Not sure exactly what text would be good for there but "coding conventions" doesn't seem appropriate.

Perhaps something along the lines of:

It ensures code quality and adherence to the official WordPress Coding Standards.

will be a lot better.

[GaryJones]

In the 10 years or so since the first commit, and the 7 years since the first release, this is the first time anyone has raised concerns about the clarity of this project's name, so you may be alone in that thought.

Historically, this project was the only place where the JavaScript coding standards were checked as well, so having it named with "PHP" in the title would have been confusing at the time.

As per https://github.com/WordPress/WordPress-Coding-Standards/pull/1925, until this project drops support for PHPCS 3.x (and PHPCS 4.x may well be years away yet anyway), it will continue to support sniffing JS and CSS files (even if other modern tools are now better suited), so again, limiting the perceived scope with a title / description change to include PHP would simply be incorrect.

The term standard is used as the terminology within PHPCS, to reference the name of the "set of sniffs", and the CLI parameter, so this naming convention is commonly understood in the wider PHP world, when the context is about automated testing with PHPCS.

Looking at Symfony as an example, for instance, they too have both the documented guidelines, and the package of sniffs, using the term "coding standard".

The project's name in composer/Packagist also uses the term wpcs, so any change there would actively break CI/CD processes, and while there are technical ways around it, the ambiguity and historical references across the web doesn't make it a sound choice.

re "coding conventions": the sniffs do more than look at code style - they advise on which functions should be used or not used, how classes should be put into their own files, and so on. I don't have a hard opinion against removing the "coding conventions, especially" bit as there are more important things to move forward, like the standard itself. However, the WPCS is not only for WP Core, but also for the wider WP community and the WordPress-Extra standard contains additional checks, not used by Core (as they are not in the Coding Standards handbook), but which advise on coding conventions.

[azaozz]

In the 10 years or so since the first commit, and the 7 years since the first release, this is the first time anyone has raised concerns about the clarity of this project's name...

Yes, I was quite surprised too, but then thinking more about it, it seems confusing... What does "WordPress Coding Standards" really mean? Is it the actual standards (i.e. the written rules) or is it the software that implements and enforces these rules? Or both?

I came across this "tooltip" on the make/core site:

It seems imported from some sort of a glossary. Do you believe this is the right explanation of "WordPress Coding Standards", especially for non-technical readers? I.e. are the standards "a collection of sniffs for PHP_CodeSniffer" or are they the written standards in the Coding Standards Handbook that WP has been following for 13-14 years?

Thankfully the above tooltip is pretty easy to fix. Just wondering how many other places may be confused by this repo's name.

will continue to support sniffing JS and CSS files...

Sure, technically that may be the case but don't think this is used in WP. Also thinking this is besides the point. Two different things/places that have the same name will always be confusing.

The project's name in composer/Packagist also uses the term wpcs, so any change there would actively break CI/CD

Yes, as I mentioned above don't think it is feasible to rename the actual repo or to change the WPCS acronym (including its use in the code). Was just thinking it would be better to try to reduce confusion by changing the title and text that appear on the front page of this repo.

re "coding conventions": the sniffs do more than look at code style - they advise on which functions should be used or not used...

Yes I understand. Was thinking it may be a good idea to "sync" terms used in the WP coding standards handbook and here in this repo, purely for consistency. Seems "coding standards" is used a lot and many people understand that term, while "coding conventions" is used pretty rarely.

As I mentioned above I'm guessing the name of this project and this repo seems to have followed the PHPCS name/acronym. That probably made a lot of sense all these years ago. However it seems rather confusing today especially with WordPress using so many different tools that are different for different parts of the code and for different repos.

[GaryJones]

then thinking more about it, it seems confusing...

...to you, maybe. But, you're intelligent, and I know that you know the difference, so it's not really confusing.

I came across this "tooltip" on the make/core site

As a standalone, it probably is the wrong explanation on that tooltip, but it depends on the context of the rest of the sentence.

Just wondering how many other places may be confused by this repo's name.

Not enough to warrant any changes at this time. 2.1k worth of stars, 8.2M install via Packagist, and countless uses of the package elsewhere, suggests folks who need this tool understand its purpose quite fine with the existing titles and descriptions.

And it's not like we don't also link back to the documented standards in the very first paragraph of the Readme. The docs, and the package, are closely linked - it's not a huge jump for them to be represented by the same contextless name or abbreviation. Feel free to propose updating the naming on the docs if you're concerned about a clash.

Sure, technically that may be the case but don't think this is used in WP.

Doesn't matter if it's used in WP core or not - the standards and sniffs are for all projects in the WP space, and there's a commitment to support the JS and CSS tokenizers and existing sniffs in the current major version, so no renaming is possible until at least PHPCS 3.x support has been dropped and the package only contains sniffs for the PHP tokenizer.

Two different things/places that have the same name will always be confusing.

Disagree. I'm sure there are plenty of people with my name in the world, but the context of my family or friends or my employer or WordPress community or my running club, means any reference is about me specifically.

Likewise, in talking about "PHPCS standards" or "WordPress sniffs", it's known that someone means this package, and not the documentation in the handbook.

In this case, we already have a title of "WordPress Coding Standards for PHP_CodeSniffer" in the readme, and a repo description that makes it clear it's for PHPCS. No amount of changing them is going to change how uncontextual references to "WordPress Coding Standards" or "WPCS" is used outside of this repo.

I appreciate you taking the time to raise this potential need for clarity, but it's not something that I see being changed at this time.

[azaozz]

then thinking more about it, it seems confusing...

...to you, maybe.

... As a standalone, it probably is the wrong explanation...

No, not to me because I know better. It seems confusing for quite a few people in the WordPress community as evident from that wrong tooltip.

Two different things/places that have the same name will always be confusing.

Disagree. I'm sure there are plenty of people with my name in the world, but the context...

Umm, I hope you're not suggesting to rename the WordPress fork of Prettier to "WordPress Coding Standards" too? That would be appropriate so the JS naming matches the PHP naming :)

Joking aside, I'm not sure how to read that answer. Why would anybody want to increase confusion instead of reducing it...

In this case, we already have a title of "WordPress Coding Standards for PHP_CodeSniffer"

The problem is that this title doesn't seem 100% correct. There are no "coding standards" in this repo, there is software (extension/sniffs for PHP_CodeSniffer) that implement the standards as written in the handbook.

Also, a bit more explanation to help reduce the confusion caused by the duplicate naming of the repo and the collection of sniffs will really help and imho is very much needed.

[dingo-d]

How about we just fix the glossary term on wp.org?

That is a simple glossary plugin holding the terms that get certain words highlighted.

@azaozz can you suggest what you'd like to have in the glossary to make it less confusing to people? That way we can agree on what should be in the glossary, and just change the term (it's a minute change max).

As for changing the repo name and descriptions, I think Gary made really good arguments about why we shouldn't change it. That would affect a lot of people and nobody has complained about those being confusing to them in about 10 years so I see no need to change anything in the repo 🙂

[GaryJones]

The problem is that this title doesn't seem 100% correct. There are no "coding standards" in this repo, there is software (extension/sniffs for PHP_CodeSniffer) that implement the standards as written in the handbook.

It matches the use of the term "standard" as used in PHP_CodeSniffer - it have has a directory called Standards which contain the internal standards; so the package here is the standards (because there are multiple: WordPress-Core, WordPress-Extra, WordPress-Docs) for WordPress - the title makes sense.

The very first line of text after the title (and TOC) says:

"This project is a collection of PHP_CodeSniffer rules (sniffs) to validate code developed for WordPress."

It really doesn't need a title that duplicates this very clear explanation of what the package contains.

As you know, conversation can continue on a closed Issue, so there's no need to reopen this.

[azaozz]

How about we just fix the glossary term on wp.org?

@dingo-d I did that already. The remaining problem is how many other places got confused by the duplicate name and by the unclear description here? How do we fix them? And how do we prevent similar confusion in the future?

[azaozz]

As you know, conversation can continue on a closed Issue, so there's no need to reopen this.

@GaryJones Sure, as you wish. However I do not consider this matter resolved. Frankly I am quite surprised by the refusal of the maintainers of this WordPress sub-project to try to remedy the confusion around it by improving the documentation and by adding a clear explanation about what this software is and what purpose does it serve.

It's not like I'm asking for the project to be renamed, or to stop using the WPCS acronym although fixing the duplicate name would probably be for the best (and is quite possible to do with a refactoring). I'm just asking for the documentation to be improved to reduce the chances of confusion and misunderstanding. How can that be a bad thing?

[dingo-d]

The remaining problem is how many other places got confused by the duplicate name and by the unclear description here?

What are the other places where people got confused? Can you give an example of such occurrences?

I'd love to see some more information before making any kind of decision. I've given talks about the WPCS in the past and never had developers come to me with the issue you mentioned so I'm a bit confused myself as to how this seems like a problem now.

Frankly I am quite surprised by the refusal of the maintainers of this WordPress sub-project to try to remedy the confusion around it by improving the documentation and by adding a clear explanation about what this software is and what purpose does it serve.

Nobody here is against remedying any kind of confusion, it's just that this is the first time we heard that there is any kind of confusion. The readme seems quite clear:

This project is a collection of PHP_CodeSniffer rules (sniffs) to validate code developed for WordPress. 
It ensures code quality and adherence to coding conventions, especially the official WordPress Coding Standards.

It's not like I'm asking for the project to be renamed, or to stop using the WPCS acronym although fixing the duplicate name would probably be for the best (and is quite possible to do with a refactoring). I'm just asking for the documentation to be improved to reduce the chances of confusion and misunderstanding. How can that be a bad thing?

Or we could (more easily in my opinion) just change the handbook to use Coding Standards for WordPress instead of WordPress Coding Standards? The handbook is already named Coding Standards Handbook, so we could just rename the main chapter to be named Coding Standards for WordPress. That would decrease the confusion.

This is similar to what is recommended when creating custom rulesets.