@author and PHP Documentation Standards

[GlennM]

According to the PHP Documentation Standards, the @author tag should not be used in plugins, 'except in the case of maintaining it in external libraries'.

[grappler]

Where did you read this as I could not find it?

[GlennM]

Almost at the bottom of the PHP Documentation Standards page:

@author Tag It is WordPress’ policy not to use the @author tag, except in the case of maintaining it in external libraries. We do not want to imply any sort of “ownership” over code that might discourage contribution.

[AlchemyUnited]

+1 for ignoring the WP recommendation and doing the right thing and using the @author tag.

I think it's fair to just keep a list of "deviations" and why those are. I think this policy made sense years ago, I'm not so sure it's fair to assume most, if anyone, would confuse author with ownership at this point in OSS history.

[grappler]

@GlennM I understood that as a guideline for WordPress core and not for plugins.

I can see the case for not having the @author tag as normally everyone works on the code in a team or with contributors and not a single person is in charge for a specific code.

[AlchemyUnited]

I was under the impression that tag allowed for multiple "entries". Perhaps I've mis-thought?

[mAAdhaTTah]

No, I've seen it used for multiple authors.

[GlennM]

@grappler Thank you for your comment. The plugins are running on WordPress core, so why would you use other coding standards for those plugins?

I'm not saying that you can't use the @author tag in your plugin, but this is a boilerplate for plugins. In my opinion a boilerplate should adhere to the coding standards as close as possible. Otherwise you're encouraging people to start with a template which already has some 'errors' in it.

[slushman]

How would this be any different than the "Author" line required for plugin headers? I think the WP PHP standards regarding @author are intended for core contributions and Feature Plugins (REST API, Menu Customizer, etc - since they are intended to become part of core), but not for themes or plugins. Sadly, this distinction isn't specified on the standards page, so its unclear at best.

Yes, plugins and theme run on core, but they are not part of core. Having no @author makes sense for core, since no one should be able to potentially claim legal ownership of any part of WordPress itself and could if the @author tag was in a comment for code that person authored. Plugins and themes are inherently different. Someone does legally own the code even though its being offered for public consumption and contribution through GPL licensing.

Considering many developers (including core devs) use @author in their own plugins, I'd say we're clear to use it here too:

Tom McFarlin: https://github.com/tommcfarlin/title-capitalization-for-wordpress/blob/master/title-capitalization-for-wordpress.php Justin Tadlock: https://github.com/justintadlock/members/blob/master/members.php Eric Mann @ 10up: https://github.com/10up/SwiftStream/blob/master/SwiftStream.php K Adam White: https://github.com/kadamwhite/artgallery/blob/master/artgallery.php Pippin Williamson: https://github.com/affiliatewp/AffiliateWP/blob/master/affiliate-wp.php

Should we contact some of the core devs to get some clarification?

[jjeaton]

I agree with @grappler and @slushman that page is in the core handbook, not the plugin handbook. It makes sense as a core standard, but not as a plugin one. We should keep @author for plugins. I believe this is a valid interpretation of the standards doc, even if it's not perfectly strict.

[AlchemyUnited]

@jjeaton - not so sure i agree. let me try to explain.

in the sense that sometimes someone has to push forward. as long as any deviations are noted then where's the harm? esp when those are actually inline with the broader dev industry standards. yes, "The WordPress Way" matters. but so does understanding the delta between that an industry standards.

put another way, what's wrong with supplementing for the better? ;) again, esp if that's what all other (e.g.) PHP devs are doing.

[jjeaton]

@AlchemyUnited I'm not sure where we're disagreeing, it sounds like we both agree that it makes sense to keep @author, and that we don't need to strictly enforce the standards in the core handbook that may not make sense for plugins?

[AlchemyUnited]

oops. you're right,. my apologizes. i bow my head in shame. sorry.

[DevinVinson]

I'm also of the opinion that within plugins and the boilerplate specifically keeping and using the author tag is a best practice.

The class structure we are using is great for being able to drop in classes to your plugins as needed. Keeping the author tag in there facilitates that. Since there isn't anything specific about it in the plugin handbook we can fill in this for ourselves as a best practice :smile: