Comment Annotation in PHP – Benefits vs Costs

annotationsPHPprogramming practices

I have just started working with symfony2 and have run across comment annotations.

Although comment annotation is not an inherent part of PHP, symfony2 adds support for this feature.

My understanding of commenting is that it should make the code more intelligible to the human. The computer shouldn't care what is in comments.

What benefits come from doing this type of annotation versus just putting a command in the normal PHP code?

ie-

/**
 * @Route("/{id}")
 * @Method("GET")
 * @ParamConverter("post", class="SensioBlogBundle:Post")
 * @Template("SensioBlogBundle:Annot:post.html.twig", vars={"post"})
 * @Cache(smaxage="15")
 */
public function showAction(Post $post)
{
}

Best Answer

There are a few issues that immediately come to mind with comment annotations (and, particularly, symfony2's format):

  1. Developer Confusion The code you posted looks exactly like a DocBlock documentation comment. While the comments may be effectively interchangeable between the two meta-processors (each ignoring what they don't understand, or some using some other method of gracefully handling things), developers may or may not understand the purpose of a given comment, especially if they're not wholly familiar with one system or the other. Additionally, it opens the door to confusing annotations with documentation, which can lead to someone removing what they think is supposed to be documentation, but is actually "code".
  2. Potential Meta-Processor Conflicts Because of the above, what happens if one or the other meta-processor decides to be more strict and not allow what it doesn't recognize? Now your processor breaks at every conceivable point. Requiring you to spend time cleaning up, and inevitably losing something of value in the process (including time, and either documentation or annotations). If it must be done in comments (see advantages), then I would have at least gone with a different indicator to distinguish it from the documentation standard (a good example is SASS/Compass comments vs standard CSS comments; CSS /**/ comments are sent through to the compiled CSS, while non-CSS comments // are eaten by the compiler; additionally, it makes it fairly easy to distinguish between the two, simply by looking at the first two characters).
  3. Code/comment line-blurring In programming in general, code and comments are supposed to be separate. Code that's meant to be run shouldn't be in comments, usually for obvious reasons (because it doesn't run). You then start opening the door to doing other things inside comments, potentially pushing out the ability to actually comment, or having to jump through other hoops to distinguish between code-in-comment and actual comments (which will also increase compilation time/resources as the compiler has to go through more comments and determine whether they're meaningful, instead of just ignoring them all). Other alternatives I happened to see with a quick look on comments about Symfony's annotation, include C#'s style of wrapping angle brackets around annotations, Python's decorator style (basically what symfony already has, but not wrapped in comments), and probably just about any other style would be superior to doing it inside comments. (Or, to put it another way - It violates the "I don't need to look inside comments to find the source of bugs" rule.)

That said, doing something like this is not without its advantages.

  1. Adding functionality that is not available natively in the language. First and foremost, this is probably the reason it's done this way by Symfony. PHP doesn't have decorators/annotations, and therefore, if you want that feature, you have to find a way to implement it. Even more, if you want it and don't want your users to be dependent on PHP extensions (because they can't always control that level of their environment), you have to find a way to do it internally that won't break the PHP compiler. Comments are the obvious choice.

  2. Provide a clean way of adding various functionality to specific segments. Were I've seen annotations/decorators the most is Python, but you'll probably see it in a number of other languages, if you use them. For example, CherryPy uses it to expose functions as web page controllers (ie - a function with a specific decorator can be accessed by a browser, in the same way certain public functions in PHP controllers are accessed). They basically provide an "extension" capability to functions, or classes, offering utility features without cluttering the code inside the function.

Unfortunately, I don't know enough about Symfony to point out others with Symfony's format, but there's a lengthy discussion of the pros/cons of this in this Hacker News thread you might be interested in. You might also be interested in the request for change on the PHP site for native annotations.

Related Topic