[PHP-DEV] Re: [PHP-DOC] Re: [PHP-QA] Re: [PHP-DEV] Re: [PHP-QA] convention aboutfunction naming II From: Ron Chmara (ron <email protected>)
Date: 12/19/00

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 <email protected>, 520-326-6109, http://www.opus1.com/ron/
Work: rchmara <email protected>, 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.

-- 
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, e-mail: php-dev-unsubscribe <email protected>
For additional commands, e-mail: php-dev-help <email protected>
To contact the list administrators, e-mail: php-list-admin <email protected>