I love DocBlocks. When I meet developers who do not, or who dislike writing them, I get profoundly sad. Same thing when it comes to comments in code. I was once told that I write too many comments, and that I should not need them since my peers could read code just fine anyway. Sure, I said, and I can read Spanish just fine as well, but I would do a lot better if you threw in some English comments here and there.
At this point DocBlocks are fairly ubiquitous throughout the open source PHP development community. Take a look at the source code for Slim3, Laravel, Doctrine, Propel, Phinx, or anything from the Symfony folks, and you will see well documented code using both code comments and DocBlocks. Heck, even Phalcon, which is written in Zephir, is highly documented using DocBlocks. Thanks to them, any one of several documentation generators can compile API information for a library or project to help us all stay just a little more sane.
While all of this is great, I have noticed a bit of a trend in DocBlocks lately, and that is that they are being used as vehicles for either configuration, code, or both. Typically when you see such a thing it is referred to as an annotation, which is a part of the DocBlock itself. The
@return portions of a DocBlock are annotations that provide the developer and their IDE of choice important information about the API of the class, method, variable, or other structural component. There is actually a specification for these in PHP from the curators of PHPDocumentor, which lists at least the ones that the curators consider to be official.
Annotations in general are not the topic that causes me any pause, it is their usage as a mechanism that actually impacts the functionality of your code that bothers me a little bit. I see the value in documentation that DocBlocks provide, but they are now being used above the purposes of mere documentation. While DocBlocks used to represent inert pieces of information, which were useful to the human developer but otherwise ignored by the computer, they are now being parsed to inform the behavior of your code, instead of just your code being parsed to determine the behavior of your code.
Take Doctrine’s ORM for an example. You can configure your document-mapping using XML or YAML for your configuration, each of which I find equally useful, but you can also define your mapping through annotations in your actual model classes. If your class represents an entity, throw an
@Entity annotation in the DocBlock for the class, along with a
@Table annotation if you want to override the default table association scheme. Your auto-incrementing primary key can get an
@Id <span class="sd">@Column(type="integer") annotation, but do not forget the
@GeneratedValue one so the code knows it really is auto-incrementing. All of these are of course mixed in with your other annotations, should you choose to write them for the same structural entities. If you leave them out, or make a mistake in your annotating, you may have introduced bugs into your program…through your DocBlock.
None of this is really the end of the world. The PHP development team provided the ability to read DocBlocks using the Reflection suite way back in PHP 5.1.0, and developers are taking advantage of its ease and apparent power for configuration. That I find it to be a rather dirty way to implement configuration is, admittedly, one very insignificant man’s opinion. I think one could fairly argue that being able to place your configuration not close to your code, but inside your code, does provide documentary value. In many instances, such as with Doctrine’s ORM, annotations are one of several options for configuration, and one could also offer that the point is moot; if you do not wish to use it, choose the alternative that best fits your needs.
I guess really my point is that I just do not know how to feel about annotations taking on more than a documentary role. It is very possible that I am just behind the times, or am missing the real value. I am genuinely curious how others feel about the topic however. Please let me know what you think; I would love to learn some new things that might better inform my opinions.