Comment gérer les fonctions obsolètes dans la bibliothèque?

Question

Je travaille sur une bibliothèque Java et souhaiterais en supprimer certaines fonctions. Mes raisons en sont les API publiques et le nettoyage de la conception. Certains objets ont des setters, mais devraient être immuables, certaines fonctionnalités ont été mieux implémentées / plus propres dans différentes méthodes, etc.

J'ai marqué ces méthodes comme "obsolètes" et je souhaite les supprimer ultérieurement. Pour le moment, je pense à les supprimer après quelques sprints (cycles de développement de deux semaines).

Existe-t-il des "meilleures pratiques" concernant la suppression du code public redondant?

/ JaanusSiim

Answer 1

Définissez une date et publiez-la dans la balise @deprecated. Le temps imparti à la suppression dépend du nombre d'utilisateurs de votre code, de votre connexion avec eux et de la raison du changement.

Si vous avez des milliers d'utilisateurs et que vous leur parlez à peine, le délai devrait probablement être de l'ordre de plusieurs décennies: -)

Si vos utilisateurs sont vos 10 collègues et que vous les voyez tous les jours, le délai peut facilement être de l'ordre de plusieurs semaines.

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

Answer 2

Considérez-le de cette façon, le client A télécharge la dernière version de votre fichier de bibliothèque ou de votre travail de cadre. Il appuie sur Compile sur cette machine et, tout à coup, il voit des milliers d'erreurs car le fichier ou la fonction membre n'existe plus. À partir de ce moment-là, vous avez donné au client une raison de ne pas passer à la nouvelle version et de conserver l'ancienne version.

Raymond Chen répond le mieux avec son blog sur l’API win32,

Bien que notre expérience dans notre société de logiciels ait été la suivante: une fois l’API écrite, nous devons l’API jusqu’à la fin du cycle de vie du produit. Pour aider les utilisateurs à utiliser les nouvelles versions, nous proposons une compatibilité ascendante avec les anciennes commandes du nouveau framework.

Answer 3

Cela dépend de la fréquence de reconstruction du code. Par exemple, si 4 applications utilisent la bibliothèque et qu'elles sont reconstruites quotidiennement, un mois est suffisamment long pour résoudre les appels obsolètes.

De même, si vous utilisez la balise déconseillée, indiquez un commentaire sur le code qui remplace l'appel obsolète.

Answer 4

Utilisez @deprecated . étiquette. Lisez le annulation des APIs . pour plus d'informations.

Une fois que tous les utilisateurs du code vous ont dit qu'ils avaient tout nettoyé, commencez par retirer le code obsolète et attendez de voir si quelqu'un se plaint - puis dites-leur de réparer leur propre code ...

Answer 5

Etant donné qu'il s'agit d'une bibliothèque, envisagez d'archiver une version avec les fonctions obsolètes. Rendez cette version disponible sous forme de code source et sous forme compilée, en tant que solution de sauvegarde pour ceux qui n'ont pas modernisé leur code pour votre nouvelle API. (La forme binaire est nécessaire, car même vous aurez peut-être des difficultés à compiler l'ancienne version dans quelques années.) Indiquez clairement que cette version ne sera ni prise en charge ni améliorée. Marquez cette version avec un symbole symbolique dans votre système de contrôle de version. Puis avancez.

Answer 6

Cela dépend certainement de l'échelle à laquelle votre API est utilisée et de ce que vous avez promis d'emblée à vos clients.

Comme décrit par Vinko Vrsalovic, vous devez entrer une date à laquelle ils doivent s'attendre à un abandon de la fonction.

En production, s'il s'agit "simplement". Pour obtenir un code plus propre, j’ai tendance à laisser les choses en place même au-delà de la date dépréciée tant que cela ne casse rien.

Par contre, en développement, je le fais tout de suite, pour que tout soit réglé rapidement.

Answer 7

Vous pouvez être intéressé par des exemples de fonctionnement de la dépréciation dans d'autres projets. Par exemple, voici la politique dans le projet Django concernant la dépréciation de la fonction est:

  

Une version mineure peut rendre obsolètes certaines fonctionnalités des versions précédentes. Si une fonctionnalité de la version A.B est obsolète, elle continuera à fonctionner dans la version A.B + 1. Dans la version A.B + 2, l'utilisation de la fonctionnalité déclenche un PendingDeprecationWarning mais continue à fonctionner. La version A.B + 3 supprimera entièrement cette fonctionnalité.

Answer 8

dommage que vous n'utilisiez pas .Net: (

Le attribut obsolète généré génère avertissements du compilateur.