¿Cómo manejar la eliminación de funciones en la biblioteca?

Question

Estoy trabajando en una biblioteca de Java y me gustaría eliminar algunas funciones de ella. Mis razones para esto es la API pública y la limpieza del diseño. Algunos objetos tienen definidores, pero deben ser inmutables, algunas funcionalidades se han implementado mejor / más limpias en diferentes métodos, etc.

He marcado estos métodos como "obsoletos" y me gustaría eliminarlos eventualmente. En este momento estoy pensando en eliminarlos después de algunos sprints (ciclos de desarrollo de dos semanas).

¿Existen "mejores prácticas" para eliminar el código público redundante?

/ JaanusSiim

Answer 1

Establezca una fecha y publíquela en la etiqueta @deprecated. La cantidad de tiempo que se le da a la eliminación depende de la cantidad de usuarios que tenga su código, cuán bien conectado esté con ellos y la razón del cambio.

Si tienes miles de usuarios y apenas hablas con ellos, el período de tiempo probablemente debería estar en el rango de décadas :-)

Si tus usuarios son tus 10 compañeros de trabajo y los ves a diario, el marco de tiempo puede estar fácilmente en el rango de semanas.

/**
 * @deprecated
 * This method will be removed after Halloween!
 * @see #newLocationForFunctionality
 */

Answer 2

Considérelo de esta manera, el cliente A descarga la última versión de su archivo de biblioteca o trabajo de marcos. Presiona la compilación en esta máquina y, de repente, ve miles de errores porque el archivo o la función miembro ya no existe. A partir de este momento, le ha dado al cliente una razón para no actualizarse a su nueva versión y quedarse con la versión anterior.

Raymond Chen responde a esto de la mejor manera en su blog sobre la API de win32,

Sin embargo, nuestra experiencia en nuestra casa de software ha sido, una vez que se ha escrito la API, tenemos que llevar la API al final del ciclo de vida del producto. Para ayudar a los usuarios a obtener nuevas versiones, proporcionamos compatibilidad hacia atrás con los comandos antiguos en el nuevo marco.

Answer 3

Depende de la frecuencia con la que se reconstruya el código. Por ejemplo, si hay 4 aplicaciones que usan la biblioteca y se reconstruyen diariamente, un mes es un tiempo suficiente para arreglar las llamadas en desuso.

Además, si usa la etiqueta en desuso, proporcione algún comentario sobre qué código reemplaza la llamada en desuso.

Answer 4

Utilice @deprecated etiqueta. Lea el documento Depredación de API para más información.

Después de que todos los que usan el código le digan que se han limpiado de su lado, comience a eliminar el código en desuso y espere a ver si alguien se queja, luego dígales que corrijan su propio código ...

Answer 5

Dado que se trata de una biblioteca, considere archivar una versión con las funciones en desuso. Haga que esta versión esté disponible en código fuente y en forma compilada, como una solución de respaldo para aquellos que no han modernizado su código a su nueva API. (Se necesita la forma binaria, porque incluso es posible que tenga problemas para compilar la versión anterior en algunos años). Deje en claro que esta versión no será compatible ni mejorada. Etiquete esta versión con un símbolo simbólico en su sistema de control de versiones. Luego avanza.

Answer 6

Sin duda, depende de la escala de uso de su API y lo que prometió por adelantado a sus clientes.

Según lo descrito por Vinko Vrsalovic, debe ingresar una fecha en la que tengan que esperar el abandono de la función.

En producción, si es " simplemente " Para obtener un código más limpio, tiendo a dejar las cosas en su lugar incluso después de la fecha de desaprobación, siempre y cuando no rompa nada.

Por otro lado, en el desarrollo, lo hago inmediatamente, para que las cosas se resuelvan rápidamente.

Answer 7

Puede que te interesen los ejemplos de cómo funciona la desaprobación en otros proyectos. Por ejemplo, aquí sigue lo que la política en el proyecto Django para la eliminación de funciones is:

  

Una versión secundaria puede dejar de usar ciertas funciones de versiones anteriores. Si una función en la versión A.B está en desuso, seguirá funcionando en la versión A.B + 1. En la versión A.B + 2, el uso de la función generará una Advertencia de Depresión Pendiente, pero continuará funcionando. La versión A.B + 3 eliminará la característica por completo.

Answer 8

Lástima que no estés utilizando .Net :(

El atributo obsoleto integrado genera el atributo advertencias del compilador.