Re: Re: convention aboutfunction naming II

Jouni Ahto wrote: > On Tue, 19 Dec 2000, Zak Greant wrote: > > Also, there was some discussion a few months ago about normalizing all of > > the function names. > > We have a lot of functions that do not conform to the standard. IIRC, the > > discussion on the phpdoc list was to create a conforming alias for each > > non-conforming function and as time permits, document that the old names are > > deprecated. Then perhaps next major release or two - PHP 5 or 6 -the old > > names stop working. > Just to note, one big problem will be the documentation. With one > conforming to the rules and (one|two|three|...) non-conforming names, it's > going to be a bit hard. Or at least a bit hard to use the documentation. That was actually one of the first things that introduced this issue. :-) Most names may have one revision (three? havn't seen that yet). The doc list passed around some ideas, it was also discussed on php-dev, and the current results of those discussions are in there....(see below) > I > haven't seen any good solutions in DocBook XML for this. Tagging something > as <note>... In PHP ?.--?.?, this function foo_bar_create was called > FooBarCreate ...</note><note>... In PHP ?.?.--?, this function > FooBarCreate was called FooBar ...</note> isn't it. Only the current, official, name of the current, official, function will be completely documented. The others are documented as deprecated variants on the name.... so the above is very close. It sure beats having a separate manual entry each for FooBar, Foo_Bar, FoBar, or a different set of manual pages for each change. This too, is part of the documentation... phpdoc/README. > PHP_FALIAS_WILL_BE_DEPRECATED_SOMEDAY(foo, bar [, ...]) > PHP_FALIAS_WILL_BE_DEPRECATED_VERY_SOON(foo, bar [, ...]) > PHP_FALIAS_WILL_BE_DEPRECATED_REALLY_SOON_NOW(foo, bar [, ...]) LOL! However, I think the code will probably "age" differently, where somebody can just look through CVS for when it was aliased, if they feel like deleting it is a really important task, and bring it up then... However, in 3 years, chances are that many modules may be re-written anyways, for other reasons (see oracle/oci8), so this isn't really that critical of an issue, is it? Re: The prior dicusssion of Sept. 12: The difficulty in handling the actual retiring (not just the "official" deprecation of the usage) wasn't really concluded AFAICR, other than "not right now, but later (maybe)", with an emphasis kept on compatibility. To summarize that discussion, there were three general schools of thought: 1. Deprecate early, deprecate hard, cut out the old one entirely. 2. Age it out gracefully, somehow. The "how" wasn't clearly defined. 3. De-document it, but leave it usable, possibly forever. There was no concensus reached, other than informing current users that function names were deprecated (via the manual) was good, and that breaking lots of code at one time was a bad thing. I think that most users expect that 2 major revs will mean some major changes (hence, PHP 5, PHP 6) so function names from PHP 3 that are being "aged" may be cut out then.... it doesn't actually _break_ anything to leave them in there, though, does it? -Ronabop -- Personal: ron@opus1.com, 520-326-6109, http://www.opus1.com/ron/ Work: rchmara@pnsinc.com, 520-546-8993, http://www.pnsinc.com/ The opinions expressed in this email are not neccesarrily those of myself, my employers, or any of the other little voices in my head.