How should I mark a method as "obsolete" in JS?

Question

I am refactoring a rather large JS file that contains many unrelated methods into something that will regroup the methods together according to their usage, and renaming some of them as needed (to prevent misleading names).

However, most of the web pages that actually use this code are spread across different code branches, preventing me from doing a simple find&replace. I could do it in all the different branches, but that requires doing maintenance in 30+ branches at the same time, or probably forgetting to perform the renaming once the change is merged in the other branches (by me or other team members).

If this was C#, I could just mark the method with [Obsolete] and it would flag the necessary changes as needed, so I am looking for something somewhat equivalent. I will still provide functionality with the old interface for a while by just redirecting the calls to the new methods, but I'd like to "force" people to switch to the new interface as they work on the pages for other reasons.

Is there any other way to do something similar, besides adding a debugger; statement and a verbose comment to every method so that it breaks when developing but not in production?

Answer 1

There are a couple of things you can do in a transition period.

1. Add the @deprecated JSDoc flag.
2. Add a console warning message that indicates that the function is deprecated.

A sample:

/**
 * @deprecated Since version 1.0. Will be deleted in version 3.0. Use bar instead.
 */
function foo() {
  console.warn("Calling deprecated function!");
  bar();
}

Answer 2

Here's what we've found for Visual Studio 2013 : http://msdn.microsoft.com/en-us/library/vstudio/dn387587.aspx

It's not tested yet as we haven't made the switch, but it looks promising.

In the meantime, I am inserting a flag at page load depending on context such as :

<%
#if DEBUG
    Response.Write("<script type=\"text/javascript\"> Flags.Debug = true; </script>");
#endif
%>

and then I call a method that throws an error if the flag is true, or redirect to the new call if it is in release configuration.

Answer 3

function obsolete(oldFunc, newFunc) {
  const wrapper = function() {
    console.warn(`WARNING! Obsolete function called. Function ${oldFunc.name} has been deprecated, please use the new ${newFunc.name} function instead!`)
    newFunc.apply(this, arguments)
  }
  wrapper.prototype = newFunc.prototype
  return wrapper
}