Abordagens para depreciar um Código em JavaScript

0
34

Recentemente, tive que me aprofundar no tópico da depreciação de código em JavaScript. Eu sinto que este tópico recebe menos cobertura, embora possa desempenhar um papel fundamental em determinados projetos, especialmente quando se trabalha em equipes maiores ou se lida com APIs externas.

No terra do JavaScript, não conheço nenhum padrão real do setor para depreciar JavaScript. Pode ser diferente para qualquer equipe, biblioteca ou fornecedor.

É por isso que meu objetivo aqui é resumir minhas descobertas e pensamentos sobre esse tópico, além de algumas boas práticas quando é hora de marcar um método JavaScript obsoleto.

O que “depreciação” realmente significa?

Primeiro, vamos começar esclarecendo que a depreciação é apenas um status aplicado a um recurso de software. Isso indica que esse recurso deve ser evitado, geralmente porque foi substituído.

A depreciação também pode indicar que o recurso será removido no futuro. Os recursos são depreciados, em vez de removidos imediatamente, para fornecer compatibilidade com versões anteriores e fornecer aos programadores que usaram o recurso, o tempo necessário para adequar seu código ao novo padrão.

Além disso, um recurso obsoleto sugere que não haverá mais desenvolvimento a partir deste momento. Não deve funcionar de forma diferente de uma versão anterior (a menos que a documentação indique explicitamente outra coisa). Então, geralmente, deve ser o mesmo de quando a ação de descontinuidade aconteceu.

Ele pode funcionar ou não na última versão – não há garantias!

No entanto, como não há nenhum padrão real do setor que seja rigorosamente seguido no campo JavaScript, isso pode ser um pouco diferente para cada time, biblioteca ou fornecedor.

Quando depreciar um código e quando excluí-lo?

É importante observar que um recurso ou método de software obsoleto ainda faz parte do software. Considere o rótulo “obsoleto” como apenas um status do código. Se o recurso de software será realmente removido no futuro, depende do que a equipe de software em questão decidir.

Na minha opinião, grandes equipes ou projetos que dependem de APIs ou bibliotecas externas devem ser depreciadas primeiro e removidos posteriormente (após um tempo razoável, no entanto, você define isso). No mínimo, dê pelo menos uma versão principal antes de realmente remover o código obsoleto para que os usuários tenham a chance de se ajustar à alteração.

Você pode querer examinar o Versionamento Semântico, um conjunto simples de regras e requisitos que determinam como os números de versão são designados e incrementados. Dado um número de versão MAJOR.MINOR.PATCH, incremente a versão MAJOR quando fizer alterações de API incompatíveis, versão MINOR quando adicionar funcionalidade de uma maneira compatível com versões anteriores e versão PATCH ao fazer correções de bugs compatíveis com versões anteriores.

Se o seu software estiver mudando e evoluindo rapidamente e você estiver depreciando um recurso, tente se comunicar com seu gerente de projeto se for esperado que esse recurso seja ressuscitado posteriormente. Se você optar por descontinuar, em vez de excluir, poderá ser muito mais fácil revertê-lo, caso seja necessário.

Para equipes menores ou projetos com métodos internos e APIs, vá em frente e remova primeiro em vez de descontinuar. Às vezes, não faz sentido perder tempo e a depreciação só aumenta a complexidade apenas para seguir as melhores práticas.

 

Como marcar um método obsoleto

Aqui temos cinco boas práticas que acho serem as mais úteis:

  1. Adicione uma flag @deprecated JSDoc.
  2. Mencione a versão que o método foi descontinuado..
  3. Projete o período de tempo para esse método seja excluído, incluindo em qual versão ocorrerá. Caso contrário, com base na minha experiência, fica para sempre.🙂
  4. Use os comentários livremente para explicar a implementação para benefíciar os outros desenvolvedores ou você mesmo, no futuro. Isso é extremamente útil se o seu use-case é escrever uma biblioteca que outras pessoas usam como dependência para o trabalho deles.
  5. Adicione uma mensagem de aviso de console que indica que a função está obsoleta.

Here’s a more practical example where I use all five practices:

/**
 * 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 a repetição nos avisos de console ou caso você pretenda descontinuar vários métodos e tenha suas substituições, pode ser mais conveniente usar um helper:

/**
 * 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;
}

Empacotando

Sugiro que sua equipe fique na mesma página e herde práticas de depreciação que façam mais sentido para seu projeto ou se use-case, seja adotando as práticas que abordamos aqui ou outras.

Observe que há certos momentos em que a exclusão faz mais sentido do que a depreciação. Às vezes, investir esforços para depreciar algo simplesmente não vale a pena. Mais uma vez, depende totalmente de você e do que faz mais sentido para o seu projeto.

Você conhece outras boas práticas ao marcar um método obsoleto em JavaScript? Deixe-me saber nos comentários!

Créditos

As ideias que compartilhei aqui foram inspiradas em comentários que encontrei no Software Engineering Stack Exchange e no StackOverflow.

 

DEIXE UMA RESPOSTA

Please enter your comment!
Please enter your name here