Using Package tags in WordPress (that is, the
@package tag that you see in code comments) is one aspect of plugin development that I call into question. And it’s not because of others who have written any given plugin; it’s coming from my experience (or lack thereof).
When I first got into writing WordPress plugins, I wasn’t using features like namespaces mainly because of the mixed messages I’d received regarding PHP versions, support for them, and so on.
So I did the next best thing and used the
@package tag as defined in the phpDocumentor manual and that I’d seen so many other plugins doing in their source code.
But I noticed a conflict: There is a disconnect between how plugins are using them and how the manual defines them.
Using Package Tags in WordPress
When I first got into WordPress development, it seemed that all themes or plugins used the following convention for their tags:
And this was true of every PHP file regardless of where it was located in the project. That is, it didn’t matter if it was located in the root of the project directory or a subdirectory, or several directories deeper into the project.
I get it, too: Sometimes developers would use
@subpackage to help delineate between the root package and then where else it was located. At the time of this post, though,
@subpackage has been deprecated but
@package is still being used as it always has been.
The @package tag can be used as a counterpart or supplement to Namespaces. Namespaces provide a functional subdivision of Structural Elements where the @package tag can provide a logical subdivision in which way the elements can be grouped with a different hierarchy.
Personally, I’m not a fan of having a difference between functional subdivisions and logical subdivisions. I’d rather have them have absolute parity. I don’t mean that I don’t understand why this exists, I’m just talking about my preference within my projects.
And if that’s the case, then the manual also offers this:
If, across the board, both logical and functional subdivisions are equal is it NOT RECOMMENDED to use the @package tag, to prevent maintenance overhead.
This raises two questions:
- At what point, in WordPress-related development, did developers start using
@packageand a single project name without any organizational scheme? That is, why is nearly every package tag accompanied by “Name_Of_Project” and nothing else?
- If a project is using namespaces, why is it also using a
I’m guilty of the second question, but that has more to do with needing to break bad habits than anything else. And maybe that’s the case for others (or for you).
But if it’s not, I’m curious about the history, use, and permeation of this tag and its apparent misuse that’s so widely spread throughout WordPress development (specifically plugin development), but I tend to focus on plugins since I work with them more than anything else.