In JavaDoc veraltet oder verunglimpft?

Im JavaDoc X509Certificate getSubjectDN()heißt es:

Verunglimpft , ersetzt durch getSubjectX500Principal ().

Ich bin es gewohnt, in den for-Methoden "Veraltet" zu sehen, die nicht mehr verwendet, aber nicht verunglimpft werden sollten. Ich habe einen Fehlerbericht über diesen speziellen Fall gefunden, in dem er mit einem Kommentar geschlossen wurde:

Das ist kein Fehler. "Veraltet" darf nur in schwerwiegenden Fällen verwendet werden.

Wenn wir eine veraltete Methode verwenden, wird allgemein empfohlen, die Verwendung der Methode zu beenden.

Was ist die vorgeschlagene Aktion, wenn eine Methode als verunglimpft markiert ist ?

Die Merriam-Webster-Definition von Verunglimpfung legt nahe:

1: den Ruf angreifen von: diffamieren <Gegner verunglimpfen>
2: die Wichtigkeit oder Gültigkeit leugnen von: herabsetzen <ihre Leistungen verunglimpfen>

Nach dem , was in einem anderen verwandten Fehlern, geschrieben diffamieren / belittle scheint die Absicht der Formulierung in javadocs verwendet zu passen - Fehler - ID: 4959744 Denigrate X509Certificate.getSubjectDN () & co :

Die Methoden getSubjectDN () und getIssuerDN () in X509Certificate und getIssuerDN () in X509CRL sind problematisch . Sie geben eine nicht angegebene Klasse zurück, die die Schnittstelle java.security.Principal implementiert, deren Spezifikation sehr locker ist.

Da in den Methoden getSubjectDN () und getIssuerDN () keine zusätzliche Spezifikation vorhanden ist, dürfen Implementierungen eine beliebige implementierungsspezifische Klasse zurückgeben. Die Erfahrung in der Praxis hat gezeigt, dass dies der Fall ist, was zu einer Nichtportabilität oder Unzuverlässigkeit des Codes führt. Aus Kompatibilitätsgründen können die Spezifikationen für diese Methoden nicht geändert werden und müssen als nicht verwertbar angesehen werden.

In JDK 1.4 wurden Ersetzungsmethoden getSubjectX500Principal () & co hinzugefügt, die eine Instanz der genau definierten X500Principal-Klasse zurückgeben. Die Implementierungen dieser Methoden wurden entwickelt, um alle Probleme dieser Art zu vermeiden. Die neuen Methoden leiden jedoch unter Unterbelichtung, und Programmierer verwenden weiterhin die bekannten und intuitiver benannten Methoden getSubjectDN () & co.

Um dies zu ändern, sollten die alten Methoden getSubjectDN () und getIssuerDN () nicht mehr unterstützt werden. Dadurch wird sichergestellt, dass Entwickler, die diese Methoden verwenden, eine Warnung zur Kompilierungszeit erhalten.

AUSWERTUNG

... Die Abschreibung wurde in diesem Fall als unangemessen angesehen. Stattdessen wurden dem JavaDoc Warnhinweise hinzugefügt .

Die Tatsache, dass das Lesen der Bug-ID 5008142 Sie über dieses "verunglimpfte" Zeug verwirrt hat, scheint eher ein Fehler des Entwicklers zu sein, der sich damit befasst hat.

Sie hätten den Fehler 4959744 finden und in ihrer Bewertung verweisen sollen, anstatt eine vage Aussage "nur zur Verwendung in schwerwiegenden Fällen". Sie könnten wahrscheinlich sogar als Duplikat schließen, mit der Begründung "Abwertung wurde berücksichtigt, bewertet und zugunsten der Verunglimpfung gemäß Bug ID 4959744 abgelehnt" .

Zumindest könnten sie die Bug-ID 4959744 (möglicherweise zusammen mit 4638294 ) im Feld " Verwandte Berichte" ( siehe auch in alten bugs.sun.com iirc) ihres Bug-Trackers verweisen. Dass dies nicht getan wurde, lässt vermuten, dass sie überhaupt nicht nach verwandten Themen gesucht haben.

Nach einigem Graben konnte ich im JDK einen Blog-Beitrag namens Deprecation finden . Grundsätzlich heißt es, dass als veraltet gekennzeichnete Dinge als schädlich für die Verwendung angesehen werden und dass es einige Dinge gibt, von denen einfach abgeraten wird.

Die allgemeine Richtlinie für mehrere Feature-Releases lautet, dass JDK-Kernkomponenten nur dann als veraltet markiert werden, wenn sie aktiv schädlich sind. Wenn die Verwendung einer Klasse oder Methode nur schlecht beraten ist, reicht dies normalerweise nicht aus, um die veraltete Note zu erhalten.

Er erwähnte, dass es derzeit eine Möglichkeit gibt, ein Objekt als nicht verwendbar zu kennzeichnen, dass sie jedoch möglicherweise eine Möglichkeit hinzufügen, dies zu tun.

Irgendwann könnte diese Art von Beratung mit einer weniger schädlichen als veralteten "Verunglimpfungs" -Funktion formalisiert werden, die auf einer Kombination von Javadoc-Tags und Anmerkungen basiert, um programmatische Überprüfungen für die Verwendung dieser weniger schädlichen API-Elemente zu ermöglichen.

Obwohl ich nichts spezielles über eine Entscheidung finden kann, den Begriff Verunglimpft zu verwenden, scheint dies ziemlich nah zu sein. Und basierend darauf scheint es, dass die Aktion, die ein Entwickler ausführen sollte, die gleiche ist wie Veraltet . Verwenden Sie die Methode nicht.