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: @package Name_of_Project.

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.

Using Package Tags in WordPress

But according to the manual:

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:

  1. At what point, in WordPress-related development, did developers start using @package and a single project name without any organizational scheme? That is, why is nearly every package tag accompanied by “Name_Of_Project” and nothing else?
  2. If a project is using namespaces, why is it also using a @package tag?

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.


Join the conversation! 4 Comments

  1. On a related note, how many plugins have great inline PHPDocs, but don’t distribute or publish the generated documentation anywhere? I’m guilty of this, and fear that until I get in the habit of including documentation generation in my build process I’ll continue to fall short. I also suspect that reviewing the generated documentation regularly would probably change my habits around what I include in inline docs.

    • I was just talking with someone on Twitter about this earlier today. Specifically, we were talking about if phpDocumenter does a good job outputting actual docs. 

      Personally, I follow the rules but I don’t always generate documentation. It depends on who the user is — if they are a developer, then I’m likely to do it; if they are a client, then I usually create a wiki in the repository. 

      But after that conversation and this comment, I’m beginning to want to create a docs directory and unconditionally ship it. If nothing else, it’s going to help me in the future with maintenance.

      • No one has ever commented on the generated documentation of the plugins that I do build it for. I suspect that the inline comments are read more, but as a developer I’d appreciate at least being able to generate docs for a plugin to get an overview, especially if it’s a plugin I want to integrate with in some way.

        • I’m with you. I do both DocBlocks and inline comments (though some argue this is a code smell because the code should be readable without them). At any rate, no one has ever commented about the lack of documentation in terms of the API or functions in the code, but when I go back to revisit the code base for future work, I always appreciate it’s there (or wish it was there ;).

Leave a Reply