Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:93004
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 74.125.82.48 as permitted sender)
To: internals@lists.php.net
References: <57211D05.6020002@fleshgrinder.com>
 <a266302a-1ad1-2e98-5be2-8c9b0eb7effc@gmail.com>
 <57224957.8090504@fleshgrinder.com>
 <5d8ef1e6-1d08-bf12-b481-4f72af3f6dd9@gmail.com>
 <5722629A.4050001@fleshgrinder.com>
 <86108010-26a4-0f68-580d-6d3357ad3f7e@gmail.com>
 <57249270.4020400@fleshgrinder.com>
Message-ID: <179baa64-c0d6-828a-c684-39b162280a46@gmail.com>
Date: Sat, 30 Apr 2016 22:52:47 +0100
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101
 Thunderbird/45.0
MIME-Version: 1.0
In-Reply-To: <57249270.4020400@fleshgrinder.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] [RFC] PHP Annotations VS Attributes
From: rowan.collins@gmail.com (Rowan Collins)

On 30/04/2016 12:09, Fleshgrinder wrote:
> Erm, actually I did not claim anything [...] I previously claimed that Microsoft does a perfect job.

Just thought I'd point out this contradiction.


> That claim was based on the fact that the feature is called "Data Annotations" and that
> one can apply and create custom "Attributes" (Metadata).

It seems to me that "Data Annotations" are one particular use of a 
language feature which is called "attributes". Looking through the list 
of descendants of the base Attribute class [1], I can see lots of 
different usages, most of which don't refer to "annotations" anywhere 
that I can see, only to "applying the attribute". This is true even in 
prose introductions such "Controlling XML Serialization Using 
Attributes" [2] which has sentences like "Attributes can be used to 
control the XML serialization of an object or to create an alternate XML 
stream from the same set of classes." and "By applying a 
XmlArrayAttribute, you can change the name of the XML element, as follows."

[1] https://msdn.microsoft.com/en-us/library/system.attribute.aspx
[2] https://msdn.microsoft.com/en-us/library/2baksw0z.aspx



> One simply should not look at the term outside of the
> extension/library/namespace "Data Annotations" and everything is fine.

Why should we not look outside that namespace? What about that namespace 
makes it so special?

If we transpose that logic to PHP, are you saying that it's OK for 
php.net to refer to "attributes" to discuss the feature, as long as 
Doctrine carries on using "annotations" for its usage of that feature?



> The fact that .NET documentation is most of the time only talking about
> "Attributes" is because the documentation explains those classes and
> their usage.

Which classes?


> I do not understand why this means for you that the whole
> feature is called attributes.

Because the documentation talking about the feature calls it that. 
Repeatedly.

"The common language runtime allows you to add keyword-like descriptive 
declarations, called attributes..."
https://msdn.microsoft.com/en-us/library/5x6cd29c.aspx

"Apply the attribute to the code element by placing it immediately 
before the element."
https://msdn.microsoft.com/en-us/library/bfz783fz.aspx

"Attributes provide a powerful method of associating metadata, or 
declarative information, with code..."
https://msdn.microsoft.com/en-us/library/z0w1kczw.aspx


Helpfully, Microsoft make the C# Language Specification readily 
available, so I downloaded that 
[https://www.microsoft.com/en-us/download/details.aspx?id=7029]

The word "annotation" is used in only one context: "variance 
annotations", which are the "in" and "out" keywords that allow a Generic 
type parameter to be co- or contra-variant, and nothing to do with the 
feature we are discussing. The word "annotate" is also used in reference 
to documentation comments, and in the following sentence:

 > When an optional parameter is annotated with one of the caller info 
attributes, omitting the corresponding argument in a call does not 
necessarily cause the default parameter value to be substituted.

As far as I can see, it's not being used as a specific term in that 
sentence, and you could safely substitute "is marked with".

"Attribute" meanwhile appears 19 times *in the Table of Contents*, all 
describing the feature we are discussing - the ability to add some 
syntax next to some code to apply metadata retrievable by reflection. 
The Appendix contains a set of grammar constructions for the grammar of 
the "[ Foo (Bar) ]" syntax used to apply attributes; the grammar rules 
all use the word "attribute", never "annotation".


> I am sorry but this is about theoretical definition and not about some
> company chose to call it. Actually I am arguing against blindly
> following these companies (Facebook and/or Microsoft) and complying with
> the theoretical definitions.

Language is a funny thing: words mean what they mean because we agree on 
that meaning, and understand each other when we use it. A "theoretical 
definition" is no use at all if it's not how people actually use a word. 
Computer Science terms are doubly-cursed here, because rather than 
coining new words, we tend to stretch metaphorical use of existing terms 
from other fields, even when those fields overlap with our own.

If a language as popular and influential as C# calls this feature 
"attributes", as I hope I've demonstrated it does, then it's hard to say 
that that's the "wrong" name - it is the name everybody in that 
community uses, and they all agree and understand its meaning.


> As I wrote in the initial message regarding Perl. If the linked feature
> is *the only way* to add attributes than naming it attributes
> (standalone) is fine. However, if there are other means than same logic
> applies.

I still don't really understand what you mean by this. As far as I can 
see, the feature in Perl is exactly equivalent to the one proposed for 
PHP. Do you mean there is something in PHP which you consider to have 
prior claim to the word "attributes"?


>
> I really do not understand why the usage of the term annotation is wrong
> in the Rust example. It is a hint for the compiler that can be added by
> the programmer or the compiler. That's pretty much a perfect usage
> according to the definition of an annotation.

I didn't say it was "wrong", I said it showed that "annotation" is just 
as ambiguous a term as "attribute". Pretty much any syntax can be 
referred to as an "annotation" (see the C# "in"/"out" example earlier), 
just as pretty much any modifier or property can be referred to as an 
"attribute". So in an ideal world, we wouldn't use either term if we 
wanted to unambiguously refer to a new feature. At best, the Rust 
example is irrelevant to the discussion; at worst, it weakens the case 
for "annotation" being an unambiguous term, which I thought was part of 
your argument.


> The past and current RFCs are not proposing any attributes, they are
> proposing a system to annotate data with custom attributes.

Absolutely! But all we're deciding is what the language will call the 
overall feature - what page it will be on in the manual, what word will 
be used in the error messages, etc. In some languages, like Java, those 
resources would refer to "Annotations"; in other languages, like C#, 
those resources would refer to "Attributes".

Both terms have advantages and disadvantages, precedents and 
connotations - and both have potential ambiguities with other uses of 
the normal English words that have been borrowed.  In the end, it really 
is mostly a matter of taste.

Regards,

-- 
Rowan Collins
[IMSoP]