On 23/02/15 13:49, François Laupretre wrote: > Hi Lester, > >> De : Lester Caine [mailto:les...@lsces.co.uk] >> >> Reworking 15+ years of code to create 'dbc' versions of the existing >> annotations is another drain on available time. I can see someone >> writing a 'converter' program to populate some parts of this, but I'm >> not sure just how helpful that would be. > > *Please* read the document I reference before giving opinion.
OK hands up ... with so many competing rfc's at the moment I was getting mixed up with the 'alternative' formats. Actually I seem to have something cached wrong locally :( > The mechanism described here is based on code block information. It uses > existing information and extends the syntax to check for more complex types. > That's why I said it should fit your needs. > Not reading the document and replying negatively just you because I talked > about DbC is poor, imo. DbC is just a concept, not an implementation. While > alternate proposals may religiously copy syntax from D or Eiffel, I chose to > adapt it the PHP way. For different reasons, including the ones you give > (compatibility with pre-existing info), I chose to implement that by an > extension of doc block syntax. > So, if you want to give an opinion, please read https://wiki.php.net/rfc/dbc > first. See notes below. >> Just as going through libraries >> to see where someone has stripped the docblock > > This can be checked too, on a limited extent, as well as compatibility with > possible PHP type hints. Ideally, it shouldn't be in comments, but is was > done this way. And I am not convinced by the ' automatic conversion' way. A practical example is a package I'm trying to find some time to support - phpgedview. The original has nicely documented code, while the webtrees port reworked that to an alternate format which both made following changes impractical, but more important made the code unusable with phpdocumentor. A number of other libraries are suffering from the same 'modernization' so it would be nice to refresh the original phpdoc annotation with a modern raison-detra. > The only issue is that several list members are absolutely opposed to base > anything on doc comments, despite the fact it has proved useful for years. > Although I asked several times, none took the time to explain me why. It must > be ovious, but not to me. So, an RFC proposing to extend doc block syntax has > no chance to pass. It was already beginning in pre-discussions about DbC with > constructive posts like : "No doc block. Period.". Personally I'm 'docblock only'! And I would prefer all of this type hinting was docblock only as well. Analysing and profiling the code quality just like profiling SQL script ... a job that is done ON the code not IN the code, and if all of the overhead of annotation can be stripped simply by ignoring the comments then that has to be good? > However, I think this can be fully implemented in an extension, with no > change to the core. So, no need to approve an RFC ! The bit I don't like with this is the same as a number of other proposals. How errors are handled. Although that is just implementation. I still prefer old school program flow, and throwing exceptions are only appropriate when you are unable to process the 'error'. If variables being passed to a function don't meet the conditions then the program picks that up and produces an appropriate user message related to that particular call rather than a programmers line number. It's the difference between coding for the coder or coding for the user? triangleArea says there is a DbC error, but the user needs to be advised if possible just what value is a problem. It may be that a number that was input at speed is a character short so the variable processing and this is picked up even before triangleArea is called but it is the constraints in triangleArea that provide the programmer with the information on how to verify the inputs. That the right type is passed is identified here as well so adding that data to the function call is a waste of processing if the validation has already been done? >From a practical point of view, the annotation details may well be used to populate javascript side validation and while I can see how your 'requires' clause can be added to add the size of a variable, an already sized 'type' removes the need to add multiple 'requires' entries where a variable is not otherwise constrained. As you say, all this can be handled differently by different extensions and third party tools and the phpdoc/docblock data is flexible, but the rfc details how it will be used for a particular use senario -- Lester Caine - G8HFL ----------------------------- Contact - http://lsces.co.uk/wiki/?page=contact L.S.Caine Electronic Services - http://lsces.co.uk EnquirySolve - http://enquirysolve.com/ Model Engineers Digital Workshop - http://medw.co.uk Rainbow Digital Media - http://rainbowdigitalmedia.co.uk -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
