Well we know that Symfony and Doctrine use annotations as metadata, which is actually a bad practice as annotation is abomination in PHP, especially considering PHP’s lack of language support for annotation, which means they have to be used in comments, aka coupling comments with application code:
So I wonder, what are the best alternatives for annotation? I know we can just write plain PHP code, but I guess there’s a reason why people dont want to do this. Of course, XML, YAML, JSON can provide other mechanisms of achieving metadata, but they all have more or less other issues. I recently read a google groups conversation about Scala, in which the user Vlad Patryshev mentioned this:
I may be wrong, but the solution seems to be so specific for Java which does not have citizenship rights for functions. If it did, you would just have a decorator for your function class, and this decorator would not need an out-of-the-language notion of annotations.
So, the ultimate solution for annotation problem is to introduce first-class citizenship to functions like Scala does? In this way, we can achieve cleaner, shorter and flexible code as Annotation cannot provide? I know Python has first class citizenship for functions and methods, but it still offers annotation/attributes in its language core. It may seem strange, but I am talking about this in a language-level, like if there’s a language feature not implemented in PHP(or Java) that can effectively eliminate the needs for annotation. Do anyone of you have ideas about how annotation can be replaced by some other language features?
It’s not really the format of the annotations that make them problematic. You could take the annotations, lift them to another file e.g a file format that looked like this:
/*
@Foo
*/
public function bar();
The problem with annotations is also their only benefit: They allow you to edit metadata along with the data. This always causes problems because it tightly couples the configuration to the class. If you want to instantiate the same class with multiple configurations it becomes unclear how this is done and it essentially tightly couples the configuration to the class, you may as well store the configuration in static properties, the result is much the same.
As for alternatives JSON and YAML are perfect candidates, but so is PHP and XML. I’d argue that the metadata format itself is unimportant so would just say whatever you’re most comfortable with. JSON and PHP will be the fastest if performance is a consideration but JOSN’s lack of support for comments makes it undesirable in some situations.
That isn’t a foregone conclusion just because Tom says so. In fact the PHP community, broadly speaking, seems to be increasingly embracing annotations.
The concern you raised is essentially “comments aren’t code”. Can I presume, then, that if tomorrow PHP started treating docblocks specially – distinct from comments – then you’d be OK with it? Then I have good news. PHP already treats docblocks specially. I think it’s about time we move past thinking of docblocks as comments.
I think that’s true. I recall the people behind Symfony discussing this same issue on mailing lists. As I recall, the consensus they reached is that annotations are appropriate only for end-user code. So, for example, in our own end-user code, it’s generally OK to tie a particular action to a particular route.
It’s also worth mentioning, though, that annotations don’t set anything in stone. You can still override particular configuration values just the same as if you hadn’t used annotations. And you could even ignore the annotations entirely if you really wanted to and instantiate and configure the class however you please.
I think Tom is spot-on about the alternatives. The crucial detail with annotations is simply that the implementation and the configuration are in the same file. The alternative, of course, is to keep the implementation and configuration in separate files. Once you do that, then the configuration format doesn’t really matter. It could be XML or Yaml or JSON or plain PHP or whatever.
I agree with that, my only issue is that to the next developer looking at the code it’s very unclear how to instantiate the class in another way. If annotations aren’t used at all but exist in the code this presents a big WTF moment when they change the annotation and it doesn’t change the way the code executes.
I’d say annotations that exist in the code and then don’t alter the program flow when they look like they should are arguably worse than annotations that do as it’s needlessly confusing for anyone looking at the code.
Yeah, I know not everything TomB said must be the absolute authority, but he did raise a very good point about how annotation is used in PHP. Every novice coder is told at the beginning of his programming class that comments are comments and are never meant to alter the application code/logic. This is not just true in PHP itself, it’s a universal concept among all programming languages. If PHP starts to treat docblocks differently from comments, its another story, but since it’s not happening yet, PHP annotation are still comments and are therefore abomination. At least, this is what I truly think.
I don’t really want to get into a discussion about the pros/cons of annotations here as it’s clearly off topic, but if anything that is the weakest of the reasons I provided about why they’re problematic.
Yeah I understand, and like I said I agree with you that PHP annotation is abomination and should be avoided. Even if language-level support is added for annotation, it still suffers some problems.