[RFC] PHP Annotations VS Attributes

> Fleshgrinder <php@fleshgrinder.com> schrieb am Mi., 27. Apr. 2016 22:11: > > > I am writing this in a separate thread because of the urgency that I see > > regarding the naming of past, current, and future proposals regarding > > this functionality. > > > > It was and is proposed to create this feature with the name *Attributes* > > as Facebook did in their Hack language. Main argument is to blindly > > follow /because/. > > > > On 4/25/2016 10:31 AM, Dmitry Stogov wrote: > > > Different languages names this differently. > > > I may add an additional voting question - "annotation vs attributes?". > > > > > > > It is true and only natural that different languages choose different > > names for equivalent features but this discussion is not about taste, > > style, nor coolness. It is about natural language, proper computer > > science terminology, and what PHP users will search for in search > > engines. I already tried to explain this in the actual thread but I > > guess my attempts resulted in more confusion than clarification, let me > > try again. > > > > #### ATTRIBUTE #### > > > > The word *attribute* has several meanings in computer science and this > > is mainly due to its extremely generic nature: > > > > > a usually good quality or feature that someone or something has > > > > > > --- http://www.merriam-webster.com/dictionary/attribute > > > > > In computing, an attribute is a specification that defines a property > > > of an object, element, or file. [...] For clarity, attributes should > > > more correctly be considered metadata. An attribute is frequently and > > > generally a property of a property. > > > > > > --- https://en.wikipedia.org/wiki/Attribute_%28computing%29 > > > > This pretty much sums it up already. An attribute is the metadata that > > is attached to an element of source code. This metadata is anything > > unessential that is additionally added but not necessarily required. > > > > class A { > > var $x; > > } > > > > The `class` and `var` keywords are essential in this example and define > > the actual element and the names are required too. > > > > public final class A { > > private static int $x = 42; > > } > > > > Class A has the attributes `public` and `final`. > > Property `$x` has the attributes `private`, `static`, `int`, and `42`. > > > > All of these attributes of the class and the property add additional > > metadata to the source code elements that define their qualities or > > features and consequently their behavior and usage. > > > > http://www.onelook.com/?w=attribute&ls=a > > http://encyclopedia2.thefreedictionary.com/attribute > > > > Sebastian Bergmann already explained this but I think it is important to > > be repeated and further clarified. The word attribute is often used to > > refer to properties with additional metadata (e.g. access modifiers, > > default values, ...; illustrated above) in an OO context. This makes the > > usage of the word attribute additionally to its generic nature ambiguous > > as well: > > > > https://en.wikipedia.org/wiki/Attribute_%28computing%29 > > > > http://encyclopedia2.thefreedictionary.com/instance+attribute > > https://en.wikipedia.org/wiki/Instance_variable > > > > http://encyclopedia2.thefreedictionary.com/static+attribute > > https://en.wikipedia.org/wiki/Static_variable > > > > *All* userland implementations that are called /attributes/ in the free > > and open world deal with completely different things: > > > > https://packagist.org/search/?q=attribute > > > > Last but not least, Perl has /attribute/ support. However, Perl actually > > uses it for interaction with *all* attributes that can be set. Hence, > > this is what attributes really do. > > > > http://perldoc.perl.org/attributes.html > > > > #### ANNOTATION #### > > > > > Extra information associated with a particular point in a document or > > > program. Annotations may be added either by a compiler or by the > > > programmer. They are not usually essential to the correct function of > > > the program but give hints to improve performance. > > > > > > --- http://encyclopedia2.thefreedictionary.com/annotation > > > > http://www.onelook.com/?w=annotation&ls=a > > > > The term *annotation* is not only used by Java: > > > > https://packagist.org/search/?q=annotation > > > > https://en.wikipedia.org/wiki/Annotation > > https://en.wikipedia.org/wiki/Ruby_character > > https://en.wikipedia.org/wiki/Java_annotation > > > > https://msdn.microsoft.com/en-us/library/dd901590%28VS.95%29.aspx > > http://docs.scala-lang.org/tutorials/tour/annotations.html > > https://kotlinlang.org/docs/reference/annotations.html > > https://www.python.org/dev/peps/pep-3107/ > > https://ghc.haskell.org/trac/ghc/wiki/Annotations > > http://ceylon-lang.org/documentation/1.2/tour/annotations/ > > > http://clojure-doc.org/articles/ecosystem/core_typed/start/annotations.html > > https://www.dartlang.org/effective-dart/style/ > > ... > > > > https://rubygems.org/search?utf8=%E2%9C%93&query=annotation > > http://rustbyexample.com/scope/lifetime/explicit.html > > https://www.google.de/search?q=javascript+annotation > > ... > > > > Ignoring these facts just because Facebook did not do proper research is > > a total no go. It is also not up for a vote, it is just proper English > > and computer science terminology! > > > > Last but not least, it also ensures that users find the correct PHP > > manual page when they search for this new feature that might make it > > into core at some point. :) > > -- > > Richard "Fleshgrinder" Fussenegger > > > > I agree with all of that, +1. > > > >

> To add to your list ... > https://www.phpdoc.org/docs/latest/guides/docblocks.html > > The glossary entry is rather bare, but I would dispute THEIR statement - > "but also influences the way the application behaves." > > In my book, these comment blocks are 'annotation' is it's simplest form, > and we add tags within that annotation to make particular details of > that annotation both machine readable and humanly prominent. That some > of these keys may be used to "influences the way the application > behaves." is secondary? >

> My continuing irritation is that while subsets keep getting discussed as > duplicate elements outside of the phpdoc wrapper, there is no provision > for the annotations that would actually help data validation. >

> While I personally prefer the name "annotations", I don't see it as > particularly urgent, or nearly as clear-cut as you claim. >

> I clicked through on your MSDN link [1] because I was pretty sure .net > referred to them as "attributes", and am amused to find sentences like > this: > >> The System.ComponentModel.DataAnnotations namespace contains the > classes that are used as data attributes. > > In other words, the implementer of that particular library preferred the > word "annotations", but the language/framework itself calls them > "attributes"; here's a nice summary [2]: > >> For example, the accessibility of a method in a class is specified by > decorating it with the /method-modifiers/ |public|, |protected|, > |internal|, and |private|. C# enables programmers to invent new kinds of > declarative information, called attributes. > > So, that's one rather large ecosystem that calls them "attributes". >

> Your claims for Perl also don't make much sense: > >> Last but not least, Perl has/attribute/ support. However, Perl actually >> uses it for interaction with*all* attributes that can be set. Hence, >> this is what attributes really do. >> >> http://perldoc.perl.org/attributes.html > > None of the built-in attributes mentioned in that manual are standard > syntax used in the majority of Perl programs; in fact, they are all > marked as experimental, and most of the examples are of defining custom > attributes. As far as I can see, this is Perl's version of precisely the > feature that is being proposed for PHP. >

> I haven't looked through any of your other links to see if you've fallen > foul of similar confirmation bias, but am satisfied in my mind that > there are plenty of people outside Hack who call them "attributes". > > > [1] https://msdn.microsoft.com/en-us/library/dd901590%28VS.95%29.aspx > [2] https://msdn.microsoft.com/en-us/library/aa664611%28v=vs.71%29.aspx > > Regards,