Reading/Web/Working with legacy code

This page documents our experiences with working with modernizing legacy code.

jQuery specific migration

For consistency, prefer to use .then( successFn, failFn ) when replacing .done( successFn ).fail( failFn ) or .done( successFn ).catch( failFn ). Be aware of the return value in your callbacks though!
In general, .done( function () { ... } ).fail( function () { ... } ).always( alwaysFn ) can be replaced with .then( function () { ... alwaysFn() }, function () { ... alwaysFn() } )
Be aware of Deferred handlers with multiple parameters. A Deferred can resolve with multiple arguments passed to its callback functions while a ES6 promise can only resolve with only one argument.
When changing the return value of a function, keep in mind that $.Deferred().done() returns a JQuery.Deferred, but $.Deferred().then() returns a JQuery.Promise so you may have to update the JSDocs.
You may need to convert tests from sync to async if the tests cover code that previously relied on .done/.fail. This is because .done/.fail callbacks may be called synchronously if the Deferred has already been resolved (which is often the case with test stubs), but .then/.catch callbacks are always called asynchronously. See jQuery upgrade guide for more info and commit d42523e609 for an example
ESLint can be leveraged to forbid future usages of done, fail and always