D. J. Heap wrote:
> After thinking about it some more, I still like the '2' variant idea
> and then resetting them back to the normal name in a major version
> change -- but as a client it does seem a bit confusing. That is,
> the functions that are marked deprecated are not actually going to
> be removed. In fact, they will become the preferred function again
> with a slightly different parameter list and the '2' variants (which
> were not deprecated) will be removed.
>
> I don't have a better idea, but it does seem a little odd to me.
> Maybe just add a more detailed note about this to the doc comments
> or something?
Well, I personally don't like naming functions with a '2' suffix too
much, but regardless of that, I think the deprecation needs a bit more
thought.
I will quote a few paragraphs from the APR versioning document for
reference:
,----[ Replacing functions ]
| This gets a bit trickier. The original function must remain
| available at the link-level so that an application compiled
| against a minor version will continue to work with later minor
| versions. Further, if an application is designed to work with an
| earlier minor version, then we don't want to suddenly change the
| requirements for that application. This means that the headers
| cannot silently map an old function into a newer function, as that
| would turn an application, say, based on 1.2 into an application
| requiring the 1.4 or later release.
|
| This means that functions cannot truly be replaced. The new,
| alternate function can be made available in the header and
| applications can choose to use it (and become dependent upon the
| minor release where the function appears).
|
| It is possible to design a set of headers where a macro will
| always refer to the "latest" function available. Of course, if an
| application chooses to use this macro, then the resulting
| compiled-binary will be dependent upon whatever version it was
| compiled against. This strategy adds the new functionality for
| applications, yet retains the necessary source and binary
| compatibility for applications designed or built against previous
| minor releases.
`----
,----[ Deprecating functions ]
| ...
|
| Note that all deprecated functions will be removed at the next major
| version bump.
`----
Now, I am not saying that deprecating the non-'2' variants of the
functions would be strictly wrong. There are many ways to look at the
matter and many ways to view deprecation - but these are my views on
the matter.
To me, deprecation an awfully strong tag when placed on a function. It
is something that should chime a warning immediately. It is like
saying that "You should not be using this function."
But there is a reason to keep on using that function. Considering the
APR versioning guidelines, it is quite okay to write code against 1.1
headers that works okay on 1.0 if you don't use any of the new
features provided by the 1.1 API. Hence everything the 1.1 API
provides should be just that - additional functions that you can use
if you want to take advantage of the *new* features, knowing that you
are then dependant on that minor version.
And like already mentioned, deprecation usually means that function
will be removed in the near future. Specifying that this only means
the current form of the function, and not that the function name is
going away, is confusing to people who use the library.
I would like to use deprecation only for functions that have a strong
point against using them - something like that they will not work as
expected, or have security implications or whatever. Functions that if
Subversion library users find themselves using, they should consider
carefully the alternatives, even if it might mean that they will
require a newer minor version to work after that.
As a solution to the problem, I propose just being a bit more verbose
and not using the deprecated tag.
Simply explaining the situation in the documentation will give the
users the best grounds on making the decision over using the newer
function and forfeiting older minor version compatibility or just
sticking with the old - and also giving them an idea what is going to
happen in the future. As an example, in the WC administrative
directory lock depth case, the documentation string could simply point
the user to a respective svn_wc_adm_foo2 function, point out that it
was added since 1.1.0 (or development leading to 1.1.0) and that 2.0
will most likely have the svn_wc_adm_foo function with the parameters
of svn_wc_adm_foo2.
But most importantly, it still drives the point home and does not make
anyone jumpy over the deprecation issue.
As for the actual naming issue when a function interface is "improved"
- it can be argued both ways. Descriptive names such as *_depth point
out exactly what can be expected of the new functions, which is an
important point in my opinion. Coming up with descriptive suffixes can
be hard, though. Then again, naming them *2 underlines the fact that
they are just newer revisions of the same functions, and there is
never any question which alternative is the latest and greatest. But
it is not descriptive at all and people might have a harder time
deciding if they want to use the older or newer function.
-- Naked
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Wed Mar 17 03:17:27 2004