Sorry for bumping a 5-year-old thread, but I just wanted to profusely thank @Senky for the Code Sniffer rules ![:)]( "Smile")
In fact, I was a bit confused why these were not much more visible and available, but required several searches with different engines (!) and even some AI searching (!!!) until I finally stumbled upon this thread...
Anyway, here's some thoughts...
Just beware of the well-intended, very experienced but amateur developer!![;-)]( "Wink")
Anyway... That said, I'd love to see a page on the official documentation for extension developers with a list of official (in the sense of: rule-complying) configurations for at least the following tools:
GitHub workflows (which are already included, I'm just listing them here for completion's sake)
Optionally, PHP Mess Detector configuration (although the defaults are good enough, IMHO)
Sadly, there is a huge legacy of code in the core phpBB which is two decades old, and coding conventions have subtly changed over the years. Interestingly, the guidelines for JavaScript are pretty much contemporary (see, for instance, the usage of brackets and camelCase for most identifiers), while those for PHP are reminiscent of the olden days when WordPress was a blogging platform![;)]( "Wink")
(WordPress being a good example of a vastly popular and well-known mainstream application which uses a hopelessly outdated and hard-to-read coding style — worse even than phpBB, IMHO! — but also strictly sticks to it, for exactly the same reason as phpBB: legacy code...)
Then again, I'm pretty sure that 'code styling' is the kind of thing that cannot be put to the vote; it has to be strictly enforced from above, because, otherwise, you'd spend years to endlessly discuss if there should be trailing commas or not, or if Yoda comparisons are better or worse, and so forth, and so on, and no actual code will be written![:)]( "Smile")
So... I tend to agree with the overall concept: "these are the rules if you want to contribute code, stick to them; if you disagree, you're welcome to fork the code and rewrite it as you wish, but don't expect us to use any of it". That is, IMHO, the only way to guarantee code uniformity among a vast variety of developers with different backgrounds and personal styling tastes.
[As a side-note: some years ago, I was curious enough to learn Go — I love strictly-typed compiled languages — and, not surprisingly, the Google devs in charge of that project — who happened to be inventors of C and Perl, decades ago — also had to deal with the differing styles of writing code. So, they came up with one specific style, and force the compiler to apply it. There are a few ways to avoid the "default style" (by mistake or ignorance), which are separately caught by a built-in code-formatting tool. The result? There are no "coding standards" to discuss. All code is written using the same style. Most repos don't even accept code deliberately written in a non-standard way, or simply run a reformatting tool to make the code 100% compatible with the one and only single standard. End of discussion. If you don't like the strictness of those rules, you're welcome to go back to C or try Rust instead...]
In fact, I was a bit confused why these were not much more visible and available, but required several searches with different engines (!) and even some AI searching (!!!) until I finally stumbled upon this thread...
Anyway, here's some thoughts...
- All open-source projects have their coding standards and practices, and this is especially true of long-running projects such as phpBB. Providing the guidelines is a must, and they have been made public long ago.
- Volunteers may not have time to make sure they know all the rules by heart. In that aspect, I slightly disagree with @david63 — even experienced phpBB developers might forget the odd rule or two, possibly because the 'old' rule used in 2009 has been replaced by a 'new' rule in 2015... and unless your day job is maintaining the phpBB code, you might simply not be able to catch up with the changes over the decades.
- Thus, automated tools. These benefit developers of all kinds — newbies, veterans, experts in phpBB, experts in anything else but phpBB, those who are stronger on JavaScript than PHP, those that are stronger in PHP than JavaScript, those (like myself) that have no 'strength' in any particular programming language, etc. and so forth. All benefit from automated tools at some level.
- While the core developers prefer to work with PHP Storm, that's just an option for a few. If, like myself, you're not stuck to a single programming language, the last thing you want is to learn Yet Another IDE. There are far too many already. Some are free, some are cheap, some are neither. Whatever the reason, forcing volunteer developers to stick to a single IDE just for contributing code for one project is not a good solution. Rather, what works best are so-called 'universal' rules — which work with utilities that are not tied to specific IDEs or code editors. This is the province of things such as
.editorconfig, PHP Code Sniffer, PHP Mess Detector, and their ilk. Then it's up to each developer to integrate such tools in their own favourite code editor or IDE, but, these days, that's the easy bit! - As such, while I appreciate the work that was done with rule configuration files for PHP Storm, these are useless on any other platform/IDE/code editor. They're not even useful if you use GitHub's built-in CI tools — and while I agree that some things should be done locally and not remotely ("clean up your mess before you submit it!"), that's not an excuse. AFAIK, for instance, there are no free solutions out there which integrate GitHub Actions with rules from PHP Storm — while you have a gazillion (well, I use three different sets) that support PHP Code Sniffer directly. Which means that if you use PHP Code Sniffer locally, and you have it correctly configured, you won't need to worry with what happens remotely on GitHub.
Just beware of the well-intended, very experienced but amateur developer!
Anyway... That said, I'd love to see a page on the official documentation for extension developers with a list of official (in the sense of: rule-complying) configurations for at least the following tools:
.editorconfig — because even PHP Storm uses it!.gitignore — mentioned here and there in the docs but rarely with a full recommended configuration that includes PHP, JS, HTML, CSS, SVG...eslint.config.js — just because it's the most common JavaScript linter out therephpcs.xml — for properly configuring PHP Code Sniffer (i.e., @Senky's package!)GitHub workflows (which are already included, I'm just listing them here for completion's sake)
Optionally, PHP Mess Detector configuration (although the defaults are good enough, IMHO)
Sadly, there is a huge legacy of code in the core phpBB which is two decades old, and coding conventions have subtly changed over the years. Interestingly, the guidelines for JavaScript are pretty much contemporary (see, for instance, the usage of brackets and camelCase for most identifiers), while those for PHP are reminiscent of the olden days when WordPress was a blogging platform
(WordPress being a good example of a vastly popular and well-known mainstream application which uses a hopelessly outdated and hard-to-read coding style — worse even than phpBB, IMHO! — but also strictly sticks to it, for exactly the same reason as phpBB: legacy code...)Then again, I'm pretty sure that 'code styling' is the kind of thing that cannot be put to the vote; it has to be strictly enforced from above, because, otherwise, you'd spend years to endlessly discuss if there should be trailing commas or not, or if Yoda comparisons are better or worse, and so forth, and so on, and no actual code will be written
So... I tend to agree with the overall concept: "these are the rules if you want to contribute code, stick to them; if you disagree, you're welcome to fork the code and rewrite it as you wish, but don't expect us to use any of it". That is, IMHO, the only way to guarantee code uniformity among a vast variety of developers with different backgrounds and personal styling tastes.[As a side-note: some years ago, I was curious enough to learn Go — I love strictly-typed compiled languages — and, not surprisingly, the Google devs in charge of that project — who happened to be inventors of C and Perl, decades ago — also had to deal with the differing styles of writing code. So, they came up with one specific style, and force the compiler to apply it. There are a few ways to avoid the "default style" (by mistake or ignorance), which are separately caught by a built-in code-formatting tool. The result? There are no "coding standards" to discuss. All code is written using the same style. Most repos don't even accept code deliberately written in a non-standard way, or simply run a reformatting tool to make the code 100% compatible with the one and only single standard. End of discussion. If you don't like the strictness of those rules, you're welcome to go back to C or try Rust instead...]
Statistics: Posted by Gwyneth Llewelyn — Wed Apr 24, 2024 6:51 pm