如何处理库中的函数弃用？

Posted 2023-02-25

【中文标题】如何处理库中的函数弃用？

【英文标题】：How to handle functions deprecation in library?

【发布时间】：2010-09-14 05:04:13

【问题描述】：

我正在开发一个 Java 库，并希望从中删除一些函数。我这样做的原因是公共 API 和设计清理。一些对象有设置器，但应该是不可变的，一些功能在不同的方法中实现得更好/更清晰，等等。

我已将这些方法标记为“已弃用”，并希望最终将其删除。目前我正在考虑在几个 sprint（两周的开发周期）后删除这些。

是否有关于删除冗余公共代码的“最佳实践”？

/贾努斯西姆

【参考方案1】：

设置一个日期并在@deprecated 标记中公开它。删除的时间取决于您的代码拥有的用户数量、您与他们的联系程度以及更改的原因。

如果您有成千上万的用户并且您几乎不与他们交谈，那么时间范围可能应该在几十年的范围内:-)

如果您的用户是您的 10 位同事，并且您每天都会看到他们，那么时间范围很容易在几周范围内。

/**
 * @deprecated
 * This method will be removed after Halloween!
 * @see #newLocationForFunctionality
 */

【参考方案2】：

这样考虑，客户 A 会下载您的库文件或框架的最新版本。他在这台机器上点击编译，突然他看到成千上万的错误，因为成员文件或函数不再存在。从此时起，您就向客户说明了为什么不升级到新版本并继续使用旧版本的理由。

Raymond Chen 在他关于 win32 API 的博客中回答了这个问题，

不过，我们在软件公司的经验是，一旦编写了 API，我们就必须将 API 带到产品生命周期的末尾。为了帮助用户升级到新版本，我们在新框架中提供了与旧命令的向后兼容性。

【参考方案3】：

这取决于代码重建的频率。例如，如果有 4 个应用程序在使用该库，并且每天都在重建它们，那么一个月的时间足以修复已弃用的调用。

此外，如果您使用不推荐使用的标记，请提供一些注释，说明哪些代码替换了不推荐使用的调用。

【参考方案4】：

使用@deprecated 标签。阅读Deprecation of APIs 文档了解更多信息。

在使用该代码的每个人都告诉您他们已经清理完毕后，开始删除已弃用的代码并等待，看看是否有人抱怨 - 然后告诉他们修复自己的代码...

【参考方案5】：

鉴于这是一个库，请考虑使用已弃用的功能归档一个版本。以源代码和编译形式提供此版本，作为尚未将代码现代化到新 API 的人的备用解决方案。 （需要二进制形式，因为即使你可能在几年后编译旧版本也有困难。）明确表示不会支持和增强此版本。在您的版本控制系统中使用符号符号标记此版本。然后继续前进。

【参考方案6】：

这当然取决于您使用 API 的规模以及您预先向客户承诺的内容。

正如 Vinko Vrsalovic 所描述的，您应该输入一个他们必须预期放弃该功能的日期。

在生产中，如果“只是”为了获得更简洁的代码，我倾向于在不推荐使用的日期之后将其保留在适当的位置，只要它不会破坏任何东西。

另一方面，在开发过程中，我会立即进行，以便快速解决问题。

【参考方案7】：

您可能对一些其他项目中弃用如何运作的示例感兴趣。例如，下面是 policy in the Django project for function deprecation 是什么：

次要版本可能会弃用以前版本中的某些功能。如果版本 A.B 中的某个功能被弃用，它将继续在版本 A.B+1 中工作。在 A.B+2 版本中，使用该功能将引发 PendingDeprecationWarning 但将继续工作。 A.B+3 版将完全删除该功能。

【参考方案8】：

太糟糕了，你没有使用 .Net :(

内置的Obsolete 属性会生成编译器警告。

【讨论】：

@deprecated 标签也会在 Java 中产生编译器警告，如果你在命令行中使用 -Xlint:deprecation 选项，你会得到详细的消息。 .Net 在这方面并不特别。