Como lidar com as funções depreciação na biblioteca?

Question

Estou trabalhando em uma biblioteca Java e gostaria de remover algumas funções dela. Minhas razões para isso são API pública e limpeza de design. Alguns objetos têm setters, mas devem ser imutáveis, algumas funcionalidades foram implementadas melhor/mais limpas em diferentes métodos, etc.

Eu marquei esses métodos 'depreciados' e gostaria de removê -los eventualmente. No momento, estou pensando em removê -los após alguns sprints (ciclos de desenvolvimento de duas semanas).

Existem "melhores práticas" sobre a remoção do código público redundante?

/Jaanussiim

Answer 1

Defina uma data e divulgue -a na tag @Deprecated. A quantidade de tempo dada à remoção depende da quantidade de usuários que seu código tem, quão bem você está conectado com eles e o motivo da alteração.

Se você tem milhares de usuários e mal fala com eles, o prazo provavelmente deve estar no intervalo de décadas :-)

Se seus usuários são seus 10 colegas de trabalho e você os vê diariamente, o prazo pode estar facilmente no intervalo das semanas.

/**
 * @deprecated
 * This method will be removed after Halloween!
 * @see #newLocationForFunctionality
 */

Answer 2

Considere dessa maneira, o cliente e o download da versão mais recente do arquivo de biblioteca ou do trabalho de quadros. Ele atinge compilar nesta máquina e de repente ele vê milhares de erros porque o arquivo ou função do membro não existe mais. A partir deste ponto, você deu ao cliente um motivo para não atualizar para sua nova versão e ficar com a versão antiga.

Raymond Chen responde o melhor com seu blog sobre a API Win32,

No entanto, nossa experiência em nossa casa de software foi, uma vez que a API foi escrita, temos que levar a API até o final do ciclo de vida do produto. Para ajudar os usuários a novas versões, fornecemos compatibilidade com os comandos antigos na nova estrutura.

Answer 3

Depende da frequência com que o código é reconstruído. Por exemplo, se houver 4 aplicativos usando a biblioteca e eles forem reconstruídos diariamente, um mês é um tempo suficiente para corrigir as chamadas depreciadas.

Além disso, se você usar a tag depreciada, forneça alguns comentários sobre qual código substitui a chamada depreciada.

Answer 4

Utilização @deprecated etiqueta.Leia o Substituição de APIs documento para mais informações.

Depois de todos usando o código diz que eles têm limpa no seu lado, começar a remover o preterido código e esperar e ver se alguém reclama - então diga-lhes para corrigir o seu próprio código...

Answer 5

Dado que esta é uma biblioteca, considere o arquivo de uma versão com as funções.Fazer essa versão disponível tanto em código-fonte e compilados forma, como uma solução de cópia de segurança para aqueles que ainda não modernizou o seu código para a nova API.(O formato binário é necessário, porque mesmo você pode ter problemas para compilar a versão antiga em poucos anos.) Deixam claro que essa versão não vai ser apoiada e reforçada.Marca esta versão, com uma simbólica símbolo em seu sistema de controle de versão.Em seguida, avançar.

Answer 6

Isso certamente depende em qual escala a sua API é usada e o que você prometeu adiantado para seus clientes.

Como descrito por Vinko Vrsalovic, você deve inserir uma data de quando eles têm que esperar o abandono da função.

Na produção, se ele é "apenas" uma questão de ficar código mais limpo, eu tendem a deixar as coisas no lugar, mesmo passado a reprovação da data contanto que ele não quebrar nada.

Por outro lado, no desenvolvimento de eu fazê-lo imediatamente, a fim de resolver as coisas rapidamente.

Answer 7

Você pode estar interessado em exemplos de como a substituição funciona em alguns outros projetos.Por exemplo, aqui segue o que o política de Django projeto para a função de substituição é:

Uma versão menor pode desaprovar determinados recursos a partir de lançamentos anteriores.Se um recurso na versão A. B é preterido, ele vai continuar a trabalhar na versão A. B+1.Na versão A. B+2, o uso do recurso, irá aumentar um PendingDeprecationWarning mas vai continuar a trabalhar.Versão A. B+3 irá remover o recurso completamente.

Answer 8

pena que você não estiver usando .Net :(

O construído em Obsoleto atributo gera avisos do compilador.