¿En desuso o denigrado en JavaDoc?

11

En el JavaDoc para X509Certificate getSubjectDN()esto dice:

Denigrado , reemplazado por getSubjectX500Principal ().

Estoy acostumbrado a ver en desuso los métodos que ya no deberían usarse, pero no denigrados. Encontré un informe de error sobre este caso particular donde se cerró con comentarios:

Esto no es un error. "Desaprobado" está destinado a ser utilizado solo en casos graves.

Cuando estamos usando un método que está en desuso , la acción general sugerida es dejar de usar el método.

Entonces, ¿cuál es la acción sugerida cuando un método se marca como Denigrado ?

Jacob Schoen
fuente
2
Guau. He leído las respuestas, y aunque estoy seguro de que son técnicamente correctas, 'denigrado' es una palabra terrible de usar. Deberían haber usado 'Desalentado'. No es necesario escupir en el código; bastaría una advertencia.
Eric King
@Eric King, sentí lo mismo. Estaba pensando más en la línea de que, si se desanima, simplemente lo desprecia.
Jacob Schoen

Respuestas:

9

La definición de denigrar de Merriam-Webster sugiere:

1: atacar la reputación de: difamar <denigrar a los oponentes>
2: negar la importancia o validez de: menospreciar <denigrar sus logros>

Según lo que está escrito en otro error relacionado, difamación / menosprecio parece coincidir con la intención de la redacción utilizada en javadocs - ID de error: 4959744 Denigrate X509Certificate.getSubjectDN () & co :

Los métodos getSubjectDN () y getIssuerDN () en X509Certificate y getIssuerDN () en X509CRL son problemáticos . Devuelven una clase no especificada que implementa la interfaz java.security.Principal, que tiene una especificación muy flexible.

Como no hay una especificación adicional presente en los métodos getSubjectDN () y getIssuerDN (), las implementaciones pueden devolver una clase arbitraria específica de implementación. La experiencia del mundo real ha demostrado que este es el caso que resulta en la no portabilidad o la falta de fiabilidad del código. Por razones de compatibilidad, las especificaciones de esos métodos no se pueden cambiar y deben considerarse insalvables.

Los métodos de reemplazo getSubjectX500Principal () & co que devuelven una instancia de la clase X500Principal bien definida se agregaron en JDK 1.4. Las implementaciones de esos métodos se han diseñado para evitar todos los problemas de este tipo. Sin embargo, los nuevos métodos sufren de subexposición y los programadores continúan utilizando los métodos getSubjectDN () & co conocidos y más intuitivos.

Para cambiar esto, los viejos métodos getSubjectDN () y getIssuerDN () deben quedar en desuso. Eso asegurará que los desarrolladores que usan estos métodos reciban una advertencia de tiempo de compilación ...

EVALUACIÓN

... La desaprobación se consideró inapropiada en este caso. En cambio, se agregaron comentarios de precaución al JavaDoc .


El hecho de que leer el ID de error 5008142 te haya dejado confundido acerca de estas cosas "denigradas" se parece más a un error del desarrollador que se ocupó de ello.

Deberían haber encontrado el error 4959744 y referirlo en su evaluación, en lugar de una declaración vaga "destinada a ser utilizada solo en casos graves". Probablemente incluso podrían cerrarse como duplicados, con una justificación como "La desaprobación se ha considerado, evaluado y rechazado a favor de la denigración por ID de error 4959744" .

Como mínimo, podrían referir el ID de error 4959744 (tal vez junto con 4638294 ) en el campo Informes relacionados (llamado Ver también en el viejo bugs.sun.com iirc) de su rastreador de errores. El hecho de que esto no se haya hecho hace sospechar que no buscaron problemas relacionados en absoluto.

mosquito
fuente
1
La parte más difícil de @FrustratedWithFormsDesigner fue averiguar cómo ingresar "denigrado" en la página de búsqueda de Oracle para que los resultados se filtren a "bugs.sun.com". El resto fue fácil, solo revisé un puñado de resultados de búsqueda que aparecieron. "Denigrar" es una palabra bastante buena para buscar :)
mosquito
1
Mira, había usado Google para encontrar el primero, pero no me dio los otros. Probablemente debería haber buscado más. Gracias
Jacob Schoen
@jschoen Creo que esto no es culpa tuya; Expandí una respuesta sobre eso
mosquito el
4

Después de investigar un poco más, pude encontrar una publicación de blog llamada Deprecation en el JDK . Básicamente establece que las cosas marcadas como obsoletas se consideran perjudiciales para su uso, y que hay algunas cosas que simplemente se desaconsejan.

La política general para varias versiones de funciones es que los componentes centrales de JDK solo se marcan como obsoletos si son activamente dañinos. Si el uso de una clase o método no es aconsejable, por lo general no es suficiente para obtener la calificación desaprobada.

Mencionó que actualmente hay una manera de marcar un elemento como desalentado de usar, pero que eventualmente podrían agregar una forma de hacerlo.

En algún momento, este tipo de consejo podría formalizarse con una instalación de "denigración" menos dañina que la obsoleta basada en una combinación de etiquetas y anotaciones de javadoc para permitir que se realicen verificaciones programáticas para el uso de estos elementos API menos dañinos.

Si bien no puedo encontrar nada más específicamente sobre una decisión de usar el término Denigrado, esto parece bastante cercano. Y en base a esto, parece que la acción que un desarrollador debe tomar es la misma que En desuso , no use el método.

Jacob Schoen
fuente