Menu
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?
519
We use the @Deprecated annotation to deprecate a method, class, or field, and the @deprecated Javadoc tag in the comment section to inform the developer about the reason for deprecation and what can be used in its place.
These deprecated features can still be used, but should be used with caution because they are expected to be removed entirely sometime in the future. You should work to remove their use from your code. Some of these deprecated features are listed in the Annex B section of the ECMAScript specification.
What does “deprecation” actually mean? First, let's start by clarifying that the deprecation is just a status applied to a software feature. It indicates that this feature should be avoided, typically because it has been superseded. Deprecation may also indicate that the feature will be removed in the future.
Using the @Deprecated Annotation To use it, you simply precede the class, method, or member declaration with "@Deprecated." Using the @Deprecated annotation to deprecate a class, method, or field ensures that all compilers will issue warnings when code uses that program element.
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.
178
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.
8
deprecate() functionYou 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.
2
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
