Laravel 5 coming sometime in November is expected to make heavy use of annotations. In Matt Stauffer own words
In short, annotations are notes about your code that live in the DocBlock. But PHP has the ability to read and parse these notes, and so you can use them to give your code directions. Opinions on them are varied, but they’ve come to Laravel to stay.
http://mattstauffer.co/blog/laravel-5.0-route-annotations
I personally was of the opinion that code should never ever reside in comments. Its just a maintenance nightmare. However after a little research. I think I might just have been sold onto the idea. Anyways here is my good+bad list.
The bad
- Not supported by php core. This means you must use an external library to parse the docs which brings me to the next point
- Performance hit since you are running a parser (probably regex) on top of your normal code
- Confusing. Since by convention comments are not active, it may be confusing for a new developer to debug code that uses annotations
- Annotations can not be easily tested.
- Elegance. While a matter of personal opinion, code in doc blocks is ugly.
The good
- Documentation on steroids. By using annotations, your documentation will literally jump on to a whole new level. This would include better results from parsers like phpDocumentor, better context to a developer reading your code etc
- Behavior Injection. Traditionally you would need to extend a base class, say BaseController to get external functionality into your code. Annotations are a far cleaner way to do this.
- IDE Loves it. The more context you provide to an IDE the better auto-completion you get.
Popular projects that use annotations
- Doctrine. This guys are doing an awesome job with it
- PHPUnit. If you have ever tested exceptions you understand this
- Symfony.
- Laravel (From version 5)
All in all, I think annotations have their place, the decision to use or not use them should be dependent on how comfortable your developers are and how much support your framework of choice uses.
As for me, am sold. Bring it on!
