8

With Doctrine annotation processing engine for PHP, and Annotatons being used for Doctrine Entities and for Zend Form, and possibly other things, and use in other languages as well, it looks like Annotations are here to stay.

Example Annotations for Zend Form:

/**
 * @Annotation\Filter({"name":"StringTrim"})
 * @Annotation\Validator({"name":"StringLength", "options":{"min":1, "max":24}})
 * @Annotation\Validator({"name":"Regex","options":{"pattern":"/^[a-zA-Z][a-zA-Z0-9_-]{0,24}$/"}})
 * @Annotation\Attributes({"type":"text"})
 * @Annotation\Options({"label":"Username:"})
 * @Annotation\ErrorMessage("Invalid Username")
 */
public $username;

AnnotationBuilder class with the help of the processing engine will go on to build a Zend Form for me, according to the specs. Alternative ways to doing so are available via Zend\Form classes and methods.

Concerns

I notice that Annotations are basically comments, and are not subject to verification by the interpreter or a compiler, and that is part of my concern. If some syntax changes, there is no error message, and nothing immediately detectable that needs to be fixed.

You could think that mistyping a property will raise an error somewhere, but no - trying to alter some of the Annotation directives, does not issue a warning, but defaults are assumed. As such, typing up an Annotation you do not get the feedback about any syntax of semantic errors.

Question

When other ways are available (classes, methods, api, arrays), which could be statically and dynamically checked, is it detrimental to code quality and maintenance to use Annotations?

Dennis
  • 8,267
  • 6
  • 38
  • 70

2 Answers2

3

Yes, embedding functionality in a separate language in comments, which does not get syntax checked, and which fails silently on errors, is less than optimal and a maintenance headache. I think you answer this question yourself with the concerns you raise.

And yes, I would absolutely steer clear of this and use something else if it is available.

2

I went ahead and have used Annotations extensively now, it and I find it pretty cool.

The good thing is that it is fairly interchangeable with other methods should I start to totally hate it, although converting Annotations to another method will take some work. But the way it is now, it cleans up the code by having less classes, and feels "out of the way", and it works well with programmatic form control as well

I also found that there is some error notification if you do mess up badly. For example, Annotations does use a tokenizer, which tells you what it expects and where it fails. If syntax is correct but parameters are wrong, it still does fail silently, and you have to do some research on why it's not working. It is not always related to Annotations however. For example, if you add an HTML attribute to a tag via Zend\Form\Element, that attribute has to have a certain name as defined in Zend Code, i.e. "class" or "id", but not "randomClassName" (which silently does not get added)

Dennis
  • 8,267
  • 6
  • 38
  • 70