Enfoques para desaprobar código en JavaScript

Recientemente, tuve que profundizar en el tema de la obsolescencia del código en JavaScript. Siento que este tema recibe menos cobertura a pesar de que puede desempeñar un papel clave en ciertos proyectos, especialmente cuando se trabaja en equipos más grandes o se trata de API externas.

En JavaScript-land, no conozco ningún estándar industrial real para desaprobar JavaScript. Podría ser diferente según cada equipo, biblioteca o proveedor.

Es por eso que mi objetivo aquí es resumir mis hallazgos y pensamientos sobre este tema, junto con algunas buenas prácticas cuando llega el momento de marcar un método de JavaScript como obsoleto.

¿Qué significa realmente “desaprobación”?

Primero, comencemos aclarando que la desaprobación es solo un estado aplicado a una característica del software. Indica que esta característica debe evitarse, normalmente porque ha sido reemplazada.

La obsolescencia también puede indicar que la función se eliminará en el futuro. Las funciones están en desuso (en lugar de eliminarse inmediatamente) para proporcionar compatibilidad con versiones anteriores y dar tiempo a los programadores que han utilizado la función para que su código cumpla con el nuevo estándar.

Además, una característica obsoleta sugiere que no habrá ningún desarrollo adicional a partir de este momento. No debería funcionar de manera diferente a como lo hacía en una versión anterior (a menos que la documentación indique explícitamente algo más). Entonces, en general, debería ser el mismo que cuando ocurrió la acción de desaprobación.

Puede que funcione o no en la última versión, ¡sin garantías!

Sin embargo, dado que no existen verdaderos estándares de la industria que se sigan estrictamente en el mundo de JavaScript, esto podría ser ligeramente diferente según el equipo, la biblioteca o el proveedor.

¿Cuándo desaprobar el código y cuándo eliminarlo?

Es importante tener en cuenta que una característica o método de software obsoleto sigue siendo parte del software. Considere la etiqueta “obsoleta” simplemente como un estado del código. Que la función del software se elimine realmente en el futuro depende de lo que decida ese equipo de software en particular.

En mi opinión, los equipos o proyectos grandes que dependen de API o bibliotecas externas deberían quedar obsoletos primero y luego eliminarse más tarde (después de un tiempo razonable, como usted lo defina). Como mínimo, proporcione al menos un aumento de versión importante antes de eliminar el código obsoleto para que los usuarios tengan la oportunidad de adaptarse al cambio.

Es posible que desee consultar el control de versiones semántico , un conjunto simple de reglas y requisitos que dictan cómo se asignan e incrementan los números de versión. Dado un número de versión MAJOR.MINOR.PATCH, incremente la MAJORversión cuando realice cambios de API incompatibles, MINORla versión cuando agregue funcionalidad de manera compatible con versiones anteriores y PATCHla versión cuando realice correcciones de errores compatibles con versiones anteriores.

Si su software está cambiando y evolucionando rápidamente y está desaprobando una característica, intente comunicarse con su gerente de proyecto si se espera que esta característica resucite más adelante. Si elige dejar de usar, en lugar de eliminar, podría resultarle mucho más fácil revertirlo si fuera necesario.

Para equipos o proyectos más pequeños con métodos internos y API, continúe y elimine primero en lugar de desaprobarlo. A veces simplemente no tiene sentido perder el tiempo y la desaprobación solo aumenta la complejidad por el simple hecho de seguir las mejores prácticas.

Cómo marcar un método obsoleto

A continuación se presentan cinco buenas prácticas que considero más útiles:

1. Agregue una bandera @deprecated JSDoc .
2. Mencione la versión en la que el método quedó obsoleto.
3. Calcule un período de tiempo para cuando se eliminará este método, incluida la versión que se implementará. De lo contrario, según mi experiencia, se queda para siempre
4. Utilice comentarios generosamente para explicar la implementación en beneficio de otros desarrolladores o de usted mismo en el futuro. Esto es extremadamente útil si su caso de uso es escribir una biblioteca que otros usan como dependencia para su trabajo.
5. Agregue un mensaje de advertencia en la consola que indique que la función está obsoleta.

Aquí hay un ejemplo más práctico donde utilizo las cinco prácticas:

/** * A magic method that multiples digits. * * @deprecated [#1] since version 2.3 [#2]. * [#3] Will be deleted in version 3.0.  * [#4] In case you need similar behavior, implement it on you own, * preferably in vanilla JavaScript * or use the multiplyTheSameNumber method instead, * if the same number needs to be multiplied multiple times, like so: * multiplyDigits([5, 5, 5]) === multiplyTheSameNumber(5, 3) * * @param {array} _digits - digits to multiply */function multiplyDigits(_digits) {  console.warn("Calling a depricated method!"); // [#5]    // ....}

Para evitar repeticiones en las advertencias de la consola o en caso de que planee desaprobar varios métodos y tenga sus reemplazos, podría ser más conveniente utilizar un asistente:

/** * Creating a deprecated / obsolete behavior for methods in a library. * [Credits]{@link: https://stackoverflow.com/q/21726472/1333836} *  * @param  {function} replacementFunction * @param  {string} oldFnName * @param  {string} newFnName * @return {function} */const Oboslete = function(replacementFunction, oldFnName, newFnName) {    const wrapper = function() {       console.warn("WARNING! Obsolete function called. Function '" + oldFnName + "' has been deprecated, please use the new '" + newFnName + "' function instead!");        replacementFunction.apply(this, arguments);    }    wrapper.prototype = replacementFunction.prototype;    return wrapper;}

Terminando

Sugeriría que su equipo esté en la misma página y herede las prácticas de desaprobación que tengan más sentido para su proyecto o caso de uso, ya sea adoptando las prácticas que hemos cubierto aquí u otras.

Tenga en cuenta que hay ciertos momentos en los que la eliminación tiene más sentido que la desaprobación. A veces, invertir esfuerzos para desaprobar algo simplemente no vale la pena. Nuevamente, depende totalmente de usted y de lo que tenga más sentido para su proyecto.

¿Conoce otras buenas prácticas a la hora de marcar un método como obsoleto en JavaScript? ¡Házmelo saber en los comentarios!

Créditos

Las ideas que compartí aquí se inspiraron en comentarios que encontré en Software Engineering Stack Exchange y en StackOverflow .