Come gestire la deprecazione delle funzioni in libreria?

Question

Sto lavorando su una libreria Java e vorrei rimuovere alcune funzioni da essa. Le mie ragioni sono l'API pubblica e la pulizia del design. Alcuni oggetti hanno setter, ma dovrebbero essere immutabili, alcune funzionalità sono state implementate in modo migliore / più pulito in diversi metodi, ecc.

Ho contrassegnato questi metodi come "deprecati" e vorrei rimuoverli alla fine. Al momento sto pensando di rimuoverli dopo alcuni sprint (cicli di sviluppo di due settimane).

Esistono "buone pratiche" per la rimozione di codice pubblico ridondante?

/ JaanusSiim

Answer 1

Imposta una data e pubblicizzala nel tag @deprecated. La quantità di tempo dedicata alla rimozione dipende dalla quantità di utenti del codice, dalla sua connessione e dal motivo della modifica.

Se hai migliaia di utenti e parli a malapena con loro, il periodo di tempo dovrebbe probabilmente essere tra i decenni :-)

Se i tuoi utenti sono i tuoi 10 colleghi e li vedi quotidianamente, l'intervallo di tempo può essere facilmente compreso nell'intervallo di settimane.

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

Answer 2

Consideralo in questo modo, il cliente A scarica l'ultima versione del file della libreria o del lavoro della cornice. Accede alla compilazione su questa macchina e improvvisamente vede migliaia di errori perché il file o la funzione membro non esiste più. Da questo punto in poi, hai fornito al cliente un motivo per non aggiornare alla tua nuova versione e rimanere con la versione precedente.

Raymond Chen risponde al meglio con il suo blog sull'API win32,

Tuttavia, la nostra esperienza nella nostra software house è stata, una volta scritta l'API, dobbiamo portare l'API alla fine del ciclo di vita del prodotto. Per aiutare gli utenti a nuove versioni, offriamo retrocompatibilità con i vecchi comandi nel nuovo framework.

Answer 3

Dipende dalla frequenza con cui viene ricostruito il codice. Ad esempio, se ci sono 4 applicazioni che utilizzano la libreria e vengono ricostruite quotidianamente, un mese è un tempo abbastanza lungo per correggere le chiamate deprecate.

Inoltre, se si utilizza il tag deprecato, fornire alcuni commenti su quale codice sostituisce la chiamata deprecata.

Answer 4

Usa @deprecated etichetta. Leggi il documento Deprecation of API per maggiori informazioni.

Dopo che tutti quelli che usano il codice ti dicono di aver ripulito dalla loro parte, inizia a rimuovere il codice deprecato e attendi e vedi se qualcuno si lamenta, quindi digli di sistemare il proprio codice ...

Answer 5

Dato che si tratta di una libreria, prendere in considerazione l'archiviazione di una versione con le funzioni deprecate. Rendi disponibile questa versione sia in codice sorgente che in forma compilata, come soluzione di backup per coloro che non hanno modernizzato il loro codice nella tua nuova API. (È necessario il modulo binario, perché anche tu potresti avere problemi a compilare la vecchia versione tra qualche anno.) Rendi chiaro che questa versione non sarà supportata e migliorata. Contrassegna questa versione con un simbolo simbolico nel tuo sistema di controllo della versione. Quindi vai avanti.

Answer 6

Dipende sicuramente da quale scala viene utilizzata la tua API e da cosa hai promesso in anticipo ai tuoi clienti.

Come descritto da Vinko Vrsalovic, dovresti inserire una data in cui devono aspettarsi l'abbandono della funzione.

In produzione, se è " solo " per ottenere un codice più pulito, tendo a lasciare le cose a posto anche dopo la data di disapprovazione, purché non si rompa nulla.

D'altro canto in fase di sviluppo lo faccio immediatamente, al fine di sistemare le cose rapidamente.

Answer 7

Potresti essere interessato ad esempi di come funziona la deprecazione in alcuni altri progetti. Ad esempio, ecco di seguito la politica nel progetto Django per la deprecazione di funzioni è:

  

Una versione minore può deprecare alcune funzionalità rispetto alle versioni precedenti. Se una funzione nella versione A.B è obsoleta, continuerà a funzionare nella versione A.B + 1. Nella versione A.B + 2, l'uso della funzione genererà un PendingDeprecationWarning ma continuerà a funzionare. La versione A.B + 3 rimuoverà completamente la funzione.

Answer 8

peccato che non stai usando .Net :(

Viene generato l'attributo Obsolete avvisi del compilatore.