Déconseillé ou dénigré dans JavaDoc?

Dans le JavaDoc, X509Certificate getSubjectDN()il indique:

Dénigré , remplacé par getSubjectX500Principal ().

J'ai l'habitude de voir Obsolète dans les méthodes for qui ne devraient plus être utilisées, mais pas dénigrées. J'ai trouvé un rapport de bug sur ce cas particulier où il a été fermé avec un commentaire:

Ce n'est pas un bug. "Obsolète" est destiné à être utilisé uniquement dans les cas graves.

Lorsque nous utilisons une méthode obsolète , l'action générale suggérée consiste à cesser d'utiliser la méthode.

Quelle est donc l'action suggérée lorsqu'une méthode est marquée comme dénigrée ?

La définition Merriam-Webster du dénigrement suggère:

1: pour attaquer la réputation de: diffamer <dénigrer ses adversaires>
2: pour nier l'importance ou la validité de: déprécier <dénigrer leurs réalisations>

Sur la base de ce qui est écrit dans un autre bogue connexe, la diffamation / dépréciation semble correspondre à l'intention du libellé utilisé dans javadocs - ID de bogue: 4959744 Denigrate X509Certificate.getSubjectDN () & co :

Les méthodes getSubjectDN () et getIssuerDN () dans X509Certificate et getIssuerDN () dans X509CRL sont problématiques . Ils renvoient une classe non spécifiée implémentant l'interface java.security.Principal, qui a une spécification très lâche.

Étant donné qu'aucune spécification supplémentaire n'est présente dans les méthodes getSubjectDN () et getIssuerDN (), les implémentations peuvent renvoyer une classe arbitraire spécifique à l'implémentation. L'expérience du monde réel a montré que c'est le cas, ce qui entraîne la non-portabilité ou la non-fiabilité du code. Pour des raisons de compatibilité, les spécifications de ces méthodes ne peuvent pas être modifiées et elles doivent être considérées comme inaltérables.

Les méthodes de remplacement getSubjectX500Principal () & co qui renvoient une instance de la classe X500Principal bien définie ont été ajoutées dans JDK 1.4. Les implémentations de ces méthodes ont été conçues pour éviter tous les problèmes de ce type. Cependant, les nouvelles méthodes souffrent d'une sous-exposition et les programmeurs continuent d'utiliser les méthodes getSubjectDN () & co familières et plus intuitivement nommées.

Pour changer cela, les anciennes méthodes getSubjectDN () et getIssuerDN () doivent être obsolètes. Cela garantira que les développeurs qui utilisent ces méthodes reçoivent un avertissement de temps de compilation ....

ÉVALUATION

... La dépréciation a été jugée inappropriée dans ce cas. Au lieu de cela, des commentaires d'avertissement ont été ajoutés à JavaDoc .

Le fait que la lecture de l'ID de bogue 5008142 vous laisse perplexe à propos de ce truc "dénigré" ressemble plus à une faute du développeur qui s'en est occupé.

Ils auraient dû trouver le bogue 4959744 et le signaler dans leur évaluation, au lieu d'une déclaration vague "destinée à être utilisée uniquement dans les cas graves". Ils pourraient même se fermer sous forme de doublons, avec une justification comme "La dépréciation a été considérée, évaluée et rejetée en faveur du dénigrement par ID de bogue 4959744" .

À tout le moins, ils pouvaient faire référence à l'ID de bogue 4959744 (peut-être avec 4638294 ) dans le champ Rapports connexes (appelé Voir aussi dans les anciens bugs.sun.com iirc) de leur traqueur de bogues. Le fait que cela n'ait pas été fait laisse supposer qu'ils n'ont pas du tout recherché des problèmes connexes.

Après quelques recherches supplémentaires, j'ai pu trouver un article de blog intitulé Deprecation dans le JDK . Il stipule essentiellement que les choses marquées Obsolète sont considérées comme nuisibles à l'utilisation et que certaines choses sont simplement découragées.

La politique générale pour plusieurs versions de fonctionnalités est que les composants JDK principaux ne sont marqués comme obsolètes que s'ils sont activement nuisibles. Si l'utilisation d'une classe ou d'une méthode est tout simplement mal avisée, cela ne suffit généralement pas pour obtenir la note déconseillée.

Il a mentionné qu'il existe actuellement un moyen de marquer un élément comme étant découragé à utiliser, mais qu'ils pourraient éventuellement ajouter un moyen de le faire.

À un moment donné, ce type de conseil pourrait être officialisé par une fonction de «dénigrement» moins nocive que déconseillée basée sur une combinaison de balises javadoc et d'annotations pour permettre des vérifications programmatiques de l'utilisation de ces éléments d'API moins nuisibles.

Bien que je ne trouve rien d'autre spécifiquement sur une décision d'utiliser le terme dénigré, cela semble assez proche. Et sur cette base, il semble que l'action qu'un développeur devrait entreprendre soit la même que Déconseillée , n'utilisez pas la méthode.