Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:89429
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain garfieldtech.com from 66.111.4.26 cause and error)
To: internals@lists.php.net
References: <CAJGzsHriGp9PoYq++=CBQptFYZQiAsa+yxxN076BHxMQGD6HrA@mail.gmail.com>
 <5654B516.4020700@gmail.com>
 <CAESVnVpe3+9=N5rkcHp2O5cdGuFnt_EQ=sSV8ucpv5w=ox-NaA@mail.gmail.com>
 <CAJGzsHoP5mc2_demfWM3r7exN4qLThANcbcwo9SBydGpvmB1WQ@mail.gmail.com>
 <5655D82A.8020304@lsces.co.uk>
 <CAJGzsHr3XfxRGA8DSkLzAf-8AQvJPu1GMVE30PX=ScygMPgCPQ@mail.gmail.com>
 <5655E4E4.8070200@garfieldtech.com> <5655E61E.3000904@gmail.com>
 <CAJGzsHp95tp9kTB14JfUmzZ_tn-1EbD1_p9MCE59GH96AX_5DQ@mail.gmail.com>
 <5655E93F.90506@gmail.com> <5655F24B.6020401@garfieldtech.com>
 <5655F47C.3060504@gmail.com>
Message-ID: <56560921.4050703@garfieldtech.com>
Date: Wed, 25 Nov 2015 13:16:49 -0600
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:38.0)
 Gecko/20100101 Thunderbird/38.0.1
MIME-Version: 1.0
In-Reply-To: <5655F47C.3060504@gmail.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] Native Annotation Syntax
From: larry@garfieldtech.com (Larry Garfield)

On 11/25/15 11:48 AM, Rowan Collins wrote:
> Larry Garfield wrote on 25/11/2015 17:39:
>> On 11/25/15 11:00 AM, Rowan Collins wrote:
>>> I don't feel that strongly in favour of docblocks, but I don't think 
>>> the reasons given against are particularly strong.
>>>
>>> Regards,
>>
>> If you don't feel strongly in favor of them, why are you trying to 
>> make a case for them so strongly?  Just for kicks?  We don't need a 
>> "devil's advocate" at this point in the discussion...
>>
>
> Hi Larry,
>
> I don't *feel* strongly in favour or against them, but can see 
> advantages and disadvantages on both sides. Feeling strongly is not 
> the same as having a strong argument for your point of view, so just 
> because some people have expressed strong opinions against, I don't 
> see why I shouldn't challenge their reasoning, even if that does mean 
> playing devil's advocate.
>
> Which is better: basing the decision on the gut feeling of a handful 
> of people who happen to be here now, or basing it on sound reasoning 
> after thinking through the implications?
>
> Regards,

So far, the only argument FOR them is BC with existing practices. 
Everything else I've seen is, I think, ways around the issues that 
raises.  However, as has been noted the BC is spurious as it would only 
be BC with one implementation out of several, and we've never polyfiled 
other syntax-level features that I can recall.  (We've polyfilled new 
functions, but that's easy.)

By the same argument, we should have used docblocks for scalar types, 
too, so that they could be polyfilled and be BC with existing practices, 
and those would have even been fairly standardized already.  Someone 
even made that point, IIRC, and it was quickly rejected.

Whereas as a stand-alone syntax, it offers a much better distinction 
between "metadata that affects code execution" and "stuff for humans to 
read" (both for parsers and for humans).  It gives us much more 
flexibility to implement a meaningful API.  It completely avoids the 
"but comments shouldn't be code" question (which is a bigger deal than 
you'd think; it was one of the drivers behind the Backdrop fork of 
Drupal. I'm not kidding.)

That one of the lead authors of the most widely used comment-based 
annotation system in PHP is arguing what a terrible idea a comment-based 
annotation system is should carry a great deal of weight.

-- 
--Larry Garfield