phpBB Extension Coding Standard

Discussion forum for Extension Writers regarding Extension Development.
Post Reply
Senky
Extension Customisations
Extension Customisations
Posts: 2067
Joined: Thu Apr 30, 2009 8:49 pm
Name: Jakub
Contact:

phpBB Extension Coding Standard

Post by Senky » Tue May 07, 2019 3:18 pm

Hi guys,
I always liked the Coding Guidelines phpBB provides - the code is nice and clean all the time. But unlike the core, Coding Guidelines aren't strictly forced for extensions. I, however, believe that maintaining the same formatting for extensions make it easier for others to read them, contribute to them and (from the real experience) validate them. This is the reason why I created phpBB Coding Standard.

phpBB Coding Standard is a standard for PHP_CodeSniffer, making sure all your code complies with Coding Guidelines. As for now, it is not yet complete. It only features a collection of already existent sniffs (plus snake_case validators), while JS and CSS is not yet covered at all. I will be creating more sniffs in the future, but the standard is already usable.

Usage is very simple:
  • composer require --dev senky/phpbb-coding-standard "dev-master"
  • Create a file phpcs.xml.dist in your ext root directory. Typical contents should be:

    Code: Select all

    <?xml version="1.0"?>
    <ruleset>
    	<file>.</file>
    	<exclude-pattern>./build</exclude-pattern>
    	<exclude-pattern>./tests</exclude-pattern>
    	<exclude-pattern>./vendor</exclude-pattern>
    
    	<rule ref="vendor/senky/phpbb-coding-standard/ruleset.xml"/>
    </ruleset>
    
  • Then run ./vendor/bin/phpcs
  • Optionally run the sniffer in your Travis builds:

    Code: Select all

      - sh -c "if [ '$SNIFF' != '0' ]; then phpBB/vendor/bin/phpcs phpBB/ext/$EXTNAME/; fi"
The standard is already in usage in my Akismet anti-spam extension.

I welcome any suggestions. ;)

User avatar
david63
Registered User
Posts: 16068
Joined: Thu Dec 19, 2002 8:08 am
Location: Lancashire, UK
Name: David Wood
Contact:

Re: phpBB Extension Coding Standard

Post by david63 » Tue May 07, 2019 3:34 pm

Senky wrote: ↑
Tue May 07, 2019 3:18 pm
Coding Guidelines aren't required for extensions
Since when?

As far as I am aware all extensions are required to conform to phpBB's coding guidelines and whilst minor deviations would not by themselves make an extension deny worthy a complete disregard for them would.
David
Remember: You only know what you know and - you don't know what you don't know!
My CDB Contributions | How to install an extension
I will not be accepting translations for any of my extensions in Github - please post any translations in the appropriate topic.
No support requests via PM or email as they will be ignored

Senky
Extension Customisations
Extension Customisations
Posts: 2067
Joined: Thu Apr 30, 2009 8:49 pm
Name: Jakub
Contact:

Re: phpBB Extension Coding Standard

Post by Senky » Tue May 07, 2019 3:58 pm

I had a discussion yesterday with Paul, concluded that only really badly readable code is denied. Anyway, you are right - it is required, but not forced. I updated the description above.

User avatar
david63
Registered User
Posts: 16068
Joined: Thu Dec 19, 2002 8:08 am
Location: Lancashire, UK
Name: David Wood
Contact:

Re: phpBB Extension Coding Standard

Post by david63 » Tue May 07, 2019 5:53 pm

I agree that it has never been "forced" on extension developers.

I am not sure how you can force some aspects anyway. How can you deny camel case when virtually all libraries use it? If an extension developer is using variables from a library then they have to be in the case that that library is written in.

I would further argue that the coding guidelines are somewhat dated and should be brought more in line with current working practices - but that is probably a discussion for another time and another place.

In my opinion any "checking" of code conformity should take place in the EPV - you have to remember that the majority of extension developers do so as a "hobby" and are not professional programmers. We need to be very careful as to what is imposed on extension developers for fear of loosing them as there are enough factors looming whereby they may cease developing.
David
Remember: You only know what you know and - you don't know what you don't know!
My CDB Contributions | How to install an extension
I will not be accepting translations for any of my extensions in Github - please post any translations in the appropriate topic.
No support requests via PM or email as they will be ignored

Senky
Extension Customisations
Extension Customisations
Posts: 2067
Joined: Thu Apr 30, 2009 8:49 pm
Name: Jakub
Contact:

Re: phpBB Extension Coding Standard

Post by Senky » Tue May 07, 2019 7:01 pm

david63 wrote: ↑
Tue May 07, 2019 5:53 pm
In my opinion any "checking" of code conformity should take place in the EPV - you have to remember that the majority of extension developers do so as a "hobby" and are not professional programmers. We need to be very careful as to what is imposed on extension developers for fear of loosing them as there are enough factors looming whereby they may cease developing.
That is exactly why it is not part of EPV. Even seeing 100s of notices about coding guidelines would scare the users. That's why I released it independently so only experienced developers can apply it.

User avatar
VSE
Extensions Development Coordinator
Extensions Development Coordinator
Posts: 4838
Joined: Sat Jan 17, 2009 9:37 am
Location: Los Angeles, CA
Name: Matt Friedman
Contact:

Re: phpBB Extension Coding Standard

Post by VSE » Fri May 10, 2019 6:27 am

How is this any different than the code sniffing phpBB already has to make sure extensions adhere to all the same strict coding guidelines as any phpBB code submitted to github, on travis when - SNIFF="1" in .travis.yml?
Dictated but not read.
Official phpBB Extensions β˜… My Extensions & MODs
Please do not PM me for support.

Senky
Extension Customisations
Extension Customisations
Posts: 2067
Joined: Thu Apr 30, 2009 8:49 pm
Name: Jakub
Contact:

Re: phpBB Extension Coding Standard

Post by Senky » Fri May 10, 2019 7:52 am

There are additional checks such as snake_case names. But the biggest advantage is that it is easily usable on your local PC.

User avatar
david63
Registered User
Posts: 16068
Joined: Thu Dec 19, 2002 8:08 am
Location: Lancashire, UK
Name: David Wood
Contact:

Re: phpBB Extension Coding Standard

Post by david63 » Fri May 10, 2019 9:53 am

Senky wrote: ↑
Tue May 07, 2019 7:01 pm
That's why I released it independently so only experienced developers can apply it.
But surely that is not the problem. "Experienced" developers will, generally, fall into two categories:

1. Those experienced in phpBB development who know the rules and, in all probability, will not need their code checking.

2. Those who are experienced developers but not necessarily with phpBB who will code in their own preferred style and take no notice of the coding guidelines.
David
Remember: You only know what you know and - you don't know what you don't know!
My CDB Contributions | How to install an extension
I will not be accepting translations for any of my extensions in Github - please post any translations in the appropriate topic.
No support requests via PM or email as they will be ignored

Post Reply

Return to β€œExtension Writers Discussion”