![Popular open source software is more secure than unpopular open source software, because insecure software becomes unpopular fast. [That doesn't happen for proprietary software.]](../sites/all/themes/drupal4hu/images/bg-center/bg-center_4.png)
Somewhat augmenting Dries' Why the big architectural changes in Drupal 8 most excellent blog post, let me explain two architecture decisions: annotations and YAML. Both were chosen as the least bad. The decisions are obviously debatable and believe me they were (and still are) but I think it'd be helpful to give some background on the decisions. Also note there might be arguments I have forgotten.
One, annotations. These are used in the plugin system: plugins are much like PHP native interfaces with a little extra: the plugin system can discover every implementation of an interface (the default is magic namespacing), deals with metadata (by default this is provided by annotations) and provides a factory for the plugin classes. These are used for field formatters, widgets, blocks and a lot other things. So, why are we using annotations for this metadata? There are (roughly) three ways to provide metadata: in code (a hook or a static method), in an external file or annotations. We didn't want to use code because it makes static code analysis and any sort of external processing quite a bit harder not to mention that people might get the wrong idea and introduce logic there. An external file, well, that's an external file, there are already enough files or so we thought it's not desirable. It's easier to handle the class and its metadata in one file. So, annotations.
Why YAML, that's also by exclusion. First, we are looking for a file format that is both human editable and computer parsable. We did not want a Drupal-specific format (info files). We did not want XML because then the schema is the Drupalism (and XML has cooties ;) ). JSON doesn't allow comments and non-ASCII characters need escaping, that's not nice for humans. So, YAML.
Commenting on this Story is closed.
I still don't understand why we aren't using YAML files instead of annotations. We're already using YAML files for everything else, and adding extra files for everything else didn't seem to be a problem. In fact, we have hundreds (if not thousands) of new files in D8, a few more to remove some huge WTFs seems a small price to pay.
I still stick to my claim that the addition of annotations was the worst change in D8. :(
I fully agree with the first commentator. Code in comments is bad. Everyone know needs to update their editors to deal with indenting, syntax highlighting, code analysis, etc. etc.
Code should be code. Don't confuse the stuff because you can. I.e. that's the "if all you have is a hammer, everything is a nail" philosophy.
IMO it should have been code, or second best, a separate YAML file.
So know we have to teach every junior developer: yeah, some code goes in comments. I can already tell you this hugely surprised a student that's working for me. This is not the kind practice you get taught at school (Thanks!!!!).
Annotations in comments have been around in lots of languages in before, I was using them in Java years and years ago...
Not sure about programming in School (do kid get taught programming in school)? but I would have thought they crop up in University and besides that comments stopped being a free for all when we start using @param etc. etc to aid documentation.
With school I meant university basically, any place they teach you programming.
And you know why we have @param? Because it's an untyped language. So another crutch. Instead of adding proper typing, we're overloading comments even more.
If you have to put stuff in comments, it indicates your language is broken.
@param is 90% for explaining an argument's purpose, and 10% to specify its type. We would have that anyways.
And what do you mean, "add proper typing"? Port Drupal to a typed language, fork PHP or persuade its developers to complete change its fundamentals?
I found the entire Software Tailor team to very helpful and knowledgeable.
You help me understand the differences between the other systems on the market
and the Software Tailor system.Please find www.SoftwareTailor.com
Annotations in Java are integrated completely into the language and are NOT placed in comments, so that's a very unfair comparison.
The basic paradigm of annotations should be known among most programmers, and I personally don't think the step of having to include them in the comments is that hard to grasp. Of course, it would be nicer to have proper integration like in Java, but we haven't, so this is arguably the best solution for the problem.
"@param" is also an unfair comparison, since it won't throw exceptions if you add a comma.
I'm not a fan of YAML. Lots of things are more readable by humans than YAML, and yet still easily parsed by computer.
Would YAML be better than annotations? That's an interesting question.
Annotations in general are kludges. Annotations in Java and C++ are just hacks to allow adding features to compilers and allowing the code to backward compatible with older compilers without those features, since the older compilers will simply ignore the annotations as comments. I like annotations even less than YAML.
However, as chx said at the outset, both choices were the least bad choices. Getting anything done is always about choosing compromises. Don't let the perfect be the enemy of the good.
-- Chris Johnson
As stated, adding extra files is a big problem. "...We have hundreds (if not thousands) of new files in D8." Would you like to add hundreds more? Then, where do these files live, next to the class file, or in a separate directory?
It's not code in comments, that argument is invalid. Would you consider Yaml files to be code in Yaml? It's some metadata about a class. It's certainly not hard to grok.
The annotation FUD is getting tiresome. Nobody says that they're perfect, but they are a compromise between multiple bad options. The error reporting could be improved, but that's an implementation issue that can be fixed. Drupal didn't invent annotations, they have been proven to work many times before.
As someone who has written more plugins than most, and is a fan of brevity, thank you for annotations.
--twistor
One of my developers here just found out that it matters if you have your code-in-comments in a /** or in /*.
Only the first case gets picked up.
I quote: "I know have a life long hatred of code in comments."
+1