Deprecato contro Denigrato in JavaDoc?

11

Nel JavaDoc per X509Certificate getSubjectDN() indica:

Denigrated, replaced by getSubjectX500Principal().

Sono abituato a vedere Deprecato in per i metodi che non dovrebbero essere più utilizzati, ma non Denigrati. Ho trovato un rapporto bug su questo caso particolare in cui è stato chiuso con un commento:

This isn't a bug. "Deprecated" is meant to be used only in serious cases.

Quando utilizziamo un metodo che è Deprecato , l'azione generale suggerita è di smettere di usare il metodo.

Quindi qual è l'azione suggerita quando un metodo è contrassegnato come Denigrato ?

    
posta Jacob Schoen 02.11.2012 - 19:07
fonte

2 risposte

9

La definizione Merriam-Webster di denigrate suggerisce:

1: to attack the reputation of : defame <denigrate one's opponents>
2: to deny the importance or validity of: belittle <denigrate their achievements>

In base a ciò che è scritto in un altro bug correlato, defame / belittle sembra corrispondere all'intento del testo usato in javadocs - ID bac: 4959744 Denigrate X509Certificate.getSubjectDN () & co :

The methods getSubjectDN() and getIssuerDN() in X509Certificate and getIssuerDN() in X509CRL are problematic. They return an unspecified class implementing the java.security.Principal interface, which has a very loose specification.

Because no additional specification is present in the getSubjectDN() and getIssuerDN() methods, it is permissible for implementations to return an arbitrary, implementation specific class. Real world experience has shown that this is the case resulting in non-portability or unreliability of the code. For compatibility reasons, the specifications for those methods cannot be changed and they must be considered unsalvageable.

Replacement methods getSubjectX500Principal() & co that return an instance of the well-defined X500Principal class were added in JDK 1.4. The implementations of those methods have been designed to avoid all problems of this sort. However, the new methods suffer from underexposure and programmers continue to use the familiar and more intuitively named getSubjectDN() & co methods.

To change this, the old getSubjectDN() and getIssuerDN() methods should be deprecated. That will ensure that developers who use this methods receive a compile time warning....

EVALUATION

...Deprecation was considered inappropriate in this case. Instead, cautionary comments were added to the JavaDoc.

Il fatto che leggere l'ID del bug 5008142 ti abbia lasciato confuso su questa roba "denigrata" sembra più un errore dello sviluppatore che lo ha gestito.

Dovrebbero aver trovato il bug 4959744 e riferirlo nella loro valutazione, invece di una dichiarazione vaga "destinata ad essere usata solo in casi gravi". Probabilmente potrebbero anche chiudersi come duplicati, con giustificazione come "La deprecazione è stata considerata, valutata e rifiutata a favore della denigrazione per ID 4959744" .

Come minimo potrebbero riferirsi all'ID 4959744 (forse insieme a 4638294 ) nel campo Rapporti correlati (chiamato Vedi anche nel vecchio bugs.sun.com iirc) del bug tracker. Il fatto che ciò non sia stato fatto fa sospettare che non abbiano cercato affatto problemi correlati.

    
risposta data 02.11.2012 - 19:26
fonte
4

Dopo un po 'di ricerche, sono riuscito a trovare un post sul blog chiamato Deprecazione nel JDK . In pratica afferma che le cose contrassegnate come Deprecate sono considerate dannose da utilizzare e che ci sono alcune cose che sono semplicemente scoraggiate.

The general policy for several feature releases is that core JDK components are only marked as deprecated if they are actively harmful. If using a class or method is just ill-advised, that is usually not sufficient to earn the deprecated mark.

Ha affermato che attualmente esiste un modo per contrassegnare un elemento come scoraggiante da utilizzare, ma che alla fine potrebbero aggiungere un modo per farlo.

At some point, this kind of advice might be formalized with a less-harmful-than-deprecated "denigration" facility based a combination of javadoc tags and annotations to allow programmatic checks be made for usage of these less harmful API elements to.

Anche se non riesco a trovare nient'altro specificamente sulla decisione di usare il termine Denigrato , questo sembra piuttosto vicino. E in base a ciò sembra che l'azione che uno sviluppatore dovrebbe fare sia la stessa di Deprecato , non usare il metodo.

    
risposta data 02.11.2012 - 19:26
fonte

Leggi altre domande sui tag