Cómo utilizar correctamente la anotación @deprecated de Java
Regla #1: hacer Javadoc sobre cómo no hacerlo
Siempre que desapruebes un método, crea un JavaDoc para decirles a otros programadores cómo no usar este método. No se limite a decir "Este método está obsoleto, no lo utilice". Debido a que este es el significado literal de la anotación de desaprobación y @deprecated en JavaDoc, no hay absolutamente ninguna necesidad de repetirlo nuevamente. Los desarrolladores de Java, como público objetivo, conocen el significado de desaprobación.
Nombre el nuevo método para reemplazar el anterior. (¡Utilice la anotación @link!) Puede que esto no sea suficiente; la documentación del nuevo método explicará cómo usarlo. No repita (su significado literal) en JavaDoc, la documentación también debe seguir el principio DRY. Por otro lado, es posible que desee describir cómo reemplazar la llamada al método anterior y puede dar sugerencias sobre los detalles de la refactorización.
Regla #2: no hagas Javadoc cómo
Eliminar la documentación JavaDoc obsoleta. Algunos podrían argumentar que los usuarios que mantienen código heredado aún pueden necesitar esta documentación. De hecho, están utilizando un método antiguo de un repositorio antiguo. La versión antigua de la documentación todavía está ahí, grabada en piedra (o mejor dicho, en una versión del repositorio). Las versiones reales que contienen métodos obsoletos no deben contener documentación desactualizada, lo que alentaría a los programadores a continuar usándolos. Sólo hay una manera de utilizar un método obsoleto: no usarlo. JavaDoc debe describirse en tiempo real, como se indica en la regla n.° 1.
Regla #3: No explique en JavaDoc
No explique en JavaDoc por qué un método está obsoleto. Eres un desarrollador confiable, esta es tu decisión, tu elección, los demás solo pueden vivir con ello. Si lo desea, puede escribir un blog para registrar los antecedentes de la toma de decisiones de este ajuste. Esto puede ayudar, pero no debería estar escrito en JavaDoc.
La API obsoleta de JavaDoc está dedicada a explicar cómo dejar de utilizarla.
El foco es cómo. En lugar de "por qué no usarlo más (por qué)".
Regla #4: desaprobar
Si crees que necesitas desaprobar un método, ¡hazlo! Si tiene miedo de sus usuarios o no quiere que su experiencia de usuario sea más dolorosa al eliminar algún método, esta decisión le resultará dolorosa. Haga todo lo posible para garantizar la estabilidad a largo plazo de la API. Pero si hay algo que hay que desechar: tíralo inmediatamente. No se sienta culpable por el hecho de que su API no se haya diseñado teniendo en cuenta cambios futuros. Nadie puede predecir el futuro a la perfección. Después de todo, la vida sería aburrida si conocieras el futuro.