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,157
  • 5
  • 36
  • 68
  • 1
    What do you mean by "safe?" Dynamically-typed languages (which have no compile-time checks other than the language syntax) are used all the time in successful projects without ripping a hole in the universe. – Robert Harvey Feb 15 '17 at 18:38
  • updated my question slightly. Are you talking about languages such as JavaScript for example? Usually some kind of an error or warning or a notice is thrown at run-time with languages. With annotations, while checks do exist, it seems that in many cases they fail silently and assume defaults. It could be though that they are not fully mature yet as a framework, or maybe I'm not aware of how to utilize them to their full potential yet. – Dennis Feb 15 '17 at 18:47
  • @Dennis: It might depend on the language. Is it really possible in PHP to write and run code that contradicts its annotations? Is there no option or other tool to enforce them? – FrustratedWithFormsDesigner Feb 15 '17 at 18:53
  • I think better tools are possible, like in this case `AnnotationBuilder` class can do more stringent verification. Currently, it seems to silently fail on some things. If I omit a curly brace for example, `AnnotationException` is thrown. But if I mangle up a name, i.e. do `@Annotation\ValiXXXXr`, no error is thrown. Where that would cause an error if I were to use a `Validator` method directly. So by using Annotations I compromise on syntax and semantic checking for the benefit of all my form specifications being done in one place inside one file. – Dennis Feb 15 '17 at 19:30
  • As far as contradicting Annotations.. I don't think it's possible directly.. well , whatever code that is written that contradicts annotations will simply override Annotations I am guessing - kind of like using `setPropertyX` via Annotations then using `setPropertyX` some other way, the latest being honored. – Dennis Feb 15 '17 at 19:31

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.

  • 1
    thanks. I hate having answers in my own questions. But alas, since my question, I went ahead and have reluctantly used it 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 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. – Dennis Apr 10 '17 at 15:52
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,157
  • 5
  • 36
  • 68