20

Obviously it's up to the developers as to when to deprecate and when to remove, but I'm wondering how to warn developers that a JavaScript function has been deprecated?

Some popular languages (Java, C#, Python) support language level deprecation in some form.

For JavaScript though, I cannot find any standard way that developers can indicate a function has been deprecated (in code). The best I can do is follow (a large number of) release notes.

As an example, grepping the full source of jQuery 1.8 shows minimal inline comments:

# 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 and MDN don't seem to have a standard way or provide suggestions on how to handle this.

The best I've found is JSDoc's @deprecated tag.

Does anyone know if JavaScript does have a deprecation annotation that I've overlooked? Are there better or more common ways to do this?

Yves M.
  • 29,855
  • 23
  • 108
  • 144
hafichuk
  • 10,351
  • 10
  • 38
  • 53

3 Answers3

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

This is how jQuery Migrate (for the 1.8 -> 1.9 upgrade) helps people upgrading their code.

From their wiki:

To allow developers to identify and fix compatibility issues when migrating older jQuery code, the development (uncompressed) version of the plugin generates console warning messages whenever any of its functionality is called. The messages only appear once on the console for each unique message.

Florian Margaine
  • 58,730
  • 15
  • 91
  • 116
  • That's a really interesting way to deprecate features and provide backwards compatibility (if I read it correctly). So they basically are treating deprecation as a plugin. – hafichuk Jan 16 '13 at 17:45
  • This works, and I have used it. However, you need to be careful with Internet Explorer. I know in IE8 that `console.log('foo')` will cause an exception when the developer tools are not open. See https://stackoverflow.com/questions/690251/what-happened-to-console-log-in-ie8 – phylae Nov 18 '14 at 19:43
  • 2
    could be better with `console.warn('deprecated')` maybe? – Knomo Seikei Aug 05 '16 at 16:51
9

Basically there's not the way to deprecate a method/function. It's up to the developer handle the deprecated members.

The only things I guess are possible to do is to do the best effort in documenting that deprecated functions/methods, and use the @deprecated tag inside the source code documentation.

Then, some compiler (Google Closure Compiler does it, if I'm not wrong) and advanced IDE, could use this tag to verify the compiled source code and fires warnings if some deprecated function is used.

Mariano Desanze
  • 7,847
  • 7
  • 46
  • 67
Ragnarokkr
  • 2,328
  • 2
  • 21
  • 31
3

Using deprecate() function

You can use the popular util-deprecate package in addition to the JSDoc's @deprecated tag:

import deprecate from "util-deprecate";

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

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

Users see:

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

This is not really standard but it's based on Node.js util.deprecate() function.

You may need a bundler like Webpack, Browserify, Rollup, etc. to bundle an npm package for the browser.

Yves M.
  • 29,855
  • 23
  • 108
  • 144