JavaScript库应该使用已弃用的注释吗？

Question

显然，何时弃用和何时删除由开发人员决定，但我想知道如何警告开发人员JavaScript函数已被弃用？

一些流行的语言（Java、C#、Python）以某种形式支持语言级别的弃用。

对于JavaScript，我找不到任何标准方式让开发人员在代码中指示一个函数已被弃用。我所能做的最好的办法就是遵循（大量的）发行说明。

例如，在完整的jQuery 1.8源代码中，仅显示最少量的内联注释：

# curl http://code.jquery.com/jquery-1.8.0.js | grep -i depre
// jQuery.support.boxModel DEPRECATED in 1.8 since we don't support Quirks Mode
// *** attrChange attrName relatedNode srcElement  are not normalized, non-W3C, deprecated, will be removed in 1.8 ***
// Some plugins are using, but it's undocumented/deprecated and will be removed.
// Deprecated
// Limit scope pollution from any deprecated API
// Deprecated, use jQuery.browser.webkit instead

看起来W3C和MDN没有提供标准的方法或建议来处理这个问题。

我发现最好的方法是使用JSDoc的@deprecated标签。

有人知道JavaScript是否有被忽视的弃用注释吗？是否有更好或更常见的方法来处理这个问题？

- hafichuk

---

console.log('This function is deprecated.'); - Florian Margaine

@FlorianMargaine 有趣，你能把这个作为一个答案吗？你知道有哪些库使用这种方法吗？ - hafichuk

是的，jQuery Migrate（用于1.8->1.9升级）可以做到这一点。 - Florian Margaine

这个问题与 https://dev59.com/qGIk5IYBdhLWcg3wTcYr 相当相似。 - Yves M.

已弃用 = str => {if(!cmap[str]) {cmap[str]=true; console.warn(str)}} // 第一次使用特定消息时会发出警告 - QuentinUK

Answer 1

console.log('This function is deprecated.');

这就是jQuery Migrate(用于1.8->1.9升级)如何帮助升级代码的人们。

从他们的维基中：

为了让开发者能够识别和修复旧版jQuery代码的兼容性问题，插件的开发(未压缩)版本会在调用其任何功能时生成控制台警告消息。每个唯一消息只出现一次。

- Florian Margaine

---

这是一种非常有趣的方式来废弃功能并提供向后兼容性（如果我读对了的话）。所以他们基本上将废弃视为插件处理。 - hafichuk

这行代码是没问题的，我已经用过了。不过，你要小心Internet Explorer浏览器。我知道在IE8中，当开发人员工具没有打开时，console.log('foo')会导致异常。请参见https://dev59.com/jXRB5IYBdhLWcg3wNk53。 - phylae

也许加上 console.warn('deprecated') 会更好？ - Knomo Seikei

Answer 2

基本上没有一种方法可以废弃一个方法/函数。这取决于开发人员如何处理已废弃的成员。

我猜唯一可能做的事情就是尽最大努力记录已废弃的函数/方法，并在源代码文档中使用@deprecated标签。

然后，某些编译器（如果我没记错，Google Closure Compiler就是其中之一）和高级IDE，可以使用此标签验证已编译的源代码，并在使用某些已废弃的函数时发出警告。

- Ragnarokkr

Answer 3

使用deprecate()函数

您可以使用流行的util-deprecate包，以及JSDoc的@deprecated标签：

import deprecate from "util-deprecate";

/**
 * @deprecated Use bar() instead
 */
const foo = deprecate(function () {

}, "foo() is deprecated, use bar() instead");

用户看到：

foo();
// foo() is deprecated, use bar() instead
foo();
foo();

这不算是标准，但它基于Node.js的util.deprecate()函数。

你可能需要像Webpack、Browserify、Rollup等打包工具来为浏览器打包npm包。

- Yves M.