Cómo marcar una clase como en desarrollo en Java

¿Por qué no solo verifica todas las clases inestables en una rama diferente en su sistema de control de versiones?

Si ha comentado correctamente la clase, podría marcar los bits de funcionalidad incompleta como "obsoletos" y / o comentar las entrañas del método y poner un throw new UnsupportedOperationException(); .

Consulte ¿Hay algo como NotImplementedException de .NET en Java? para más detalles.

No sé tal advertencia del compilador.

En su situación, probablemente usaría la anotación @Deprecated . Cruzará las llamadas a los métodos, por lo que será obvio para los demás que algo está pasando. Cuando vean qué pasa, verán sus comentarios sobre 'no está listo para la producción' y se irán con AHA.

No creo que haya una forma estándar de marcar el código como WIP , Incomplete , o algo por el estilo.

Podría crear una nueva excepción llamada ClassUnstableException y luego aumentarla en el constructor Class3 con un mensaje que explica cómo no deben usarla. Sin embargo, esto es malo porque solo les advierte en tiempo de ejecución.

También puedes intentar hacer que la clase sea incompatible de alguna manera, y luego agregar una nota a la sección de código que dispara al compilador para que, si alguien va a arreglar el código, esperemos vea una explicación de por qué no deberían usar esa clase. Es posible que esto no funcione si usan alguna herramienta semiautomática de "solucionar este problema" que tienen algunos IDE. Esto también es malo porque podría romper compilaciones.

Podrías crear una anotación llamada WIP (ya que lo más cercano que puedo pensar es Deprecated pero en realidad no significa lo mismo) y usarla para anotar la clase. Probablemente sería un poco más de trabajo, y ¿qué apoyaría la anotación?

Finalmente, puedes ponerlo en los comentarios, pero eso solo funcionará si la gente en realidad los lee .

EDITAR:

Esto puede ser relevante: Cómo causar intencionalmente ¿Un mensaje de advertencia del compilador java personalizado?

Usted podría introducir proceso de anotación de tiempo de compilación pero esto obligaría a todos Miembros del equipo para ajustar su proceso de compilación.

Sin embargo, encuentro todo el proceso un poco confuso. Una API inestable debe separarse claramente creando una rama en su sistema de control de versiones. Si realmente tiene que estar en el resto de la base de código, se ha documentado como inestable y, sin embargo, el problema no es realmente técnico, sino que se encuentra dentro de la organización y la comunicación. Sí, podría introducir verificaciones técnicas (como el procesamiento de anotaciones) pero eso no resolvería el problema, simplemente muévalo a otro nivel.

Por lo tanto, mi recomendación es: si no puede separar el código base colocándolo en diferentes sucursales, entonces hable con la gente y explíqueles por qué no deben usar el API.

¿Por qué está ahí en primer lugar?

¿Ha ingresado código inestable en la línea principal? ¿Por qué?

El código inestable no debe ser registrado en trunk / main / master o como se llame. Se considera que se trata de un desarrollo de alto riesgo y, en lugar de ello, debería haber sido secuestrado en su propia sucursal en la que trabajó, en lugar de registrar en main.

Le recomendaría encarecidamente a usted (y al líder de su equipo) que lea Estrategias avanzadas de bifurcación de SCM . En particular, preste atención al rol de desarrollo y lo que dice sobre lo que se considera un desarrollo de alto riesgo:

  

En general, considere usar sucursales separadas para cada proyecto de alto riesgo. Los proyectos de alto riesgo se caracterizan por su gran tamaño, gran cantidad de personas, temas desconocidos, temas muy técnicos, plazos muy ajustados, fechas de entrega inciertas, requisitos incompletos o volátiles y equipos de proyectos distribuidos geográficamente. Del mismo modo, considere la posibilidad de designar una sola sucursal para el desarrollo de bajo riesgo en cada versión. Varias fuentes incluyendo [WING98] recomiendan usar la línea principal para este propósito. Considere los factores mencionados anteriormente para la línea principal antes de comprometerse con este curso de acción. El desarrollo de bajo riesgo puede tener una política diferente de la línea principal, incluso si tiene varios miembros de una familia de productos que se coordinan a través de la línea principal.

Permitir que las personas verifiquen el código inestable (o no utilizado) en la línea principal significa que confundirá los esfuerzos de desarrollo futuros al tratar de mantener este código. Cada rama y clon del representante desde ahora hasta el fin de los tiempos contendrá esto hasta que alguien diga "su código muerto" y lo elimine.

Hay algunos que dicen "bueno, si se olvida en una rama" y si bien eso puede ser cierto, haber olvidado el código muerto (e inestable) en la línea principal es muchas veces peor, ya que confunde todo el desarrollo futuro hasta que es eliminado, y luego se olvida más . Una rama con un nombre agradable de "/ fooProject / branches / WeisBigIdea" (o su equivalente) es visible y es más fácil trabajar con ella en el futuro, especialmente si funciona.

@Deprecated

Lo primero es la anotación @Deprecated . Esto va más allá del javadoc y escupe advertencias del compilador. javac proporciona un indicador -deprecation que se describe como:

  

Muestra una descripción de cada uso o anulación de un miembro o clase en desuso. Sin -deprecation , javac muestra un resumen de los archivos de origen que usan o sobrescriben clases o miembros en desuso. -deprecation es taquigrafía para -Xlint:deprecation .

Como se señaló, esto va más allá de las advertencias del compilador estándar.

En muchos IDE, los métodos y valores desaprobados se muestran tachados:

foo.bar();

Y produciría una salida como:

$ javac -Xlint:all Foo.java Bar.java
Bar.java:2: warning: [deprecation] Foo in unnamed package has been deprecated
interface Bar extends Foo { }
                      ^

Dependiendo de la estructura de compilación, es posible que haya advertencias que interrumpan la compilación. Esto solo rompería la compilación si se usara una de tus clases (no si simplemente se compilara).

@CustomAnnotation

Hay muchos enfoques para esto. Por ejemplo, la javac ligera @ Anotación de advertencia que proporciona un procesador de anotaciones que dispara una advertencia en tiempo de compilación cuando algo con esa anotación se utiliza ( un tutorial de netbeans sobre procesadores de anotaciones personalizados para que pueda tener una idea de lo que está pasando detrás de las escenas).

Oracle incluso describe un ejemplo de uso de anotaciones personalizadas para una anotación @Unfinished en Making la mayoría de los metadatos de Java, Parte 2: Anotaciones personalizadas .

Con el AnnotationProcessor , puede ejecutar un código arbitrario en tiempo de compilación. Depende de usted decidir qué quiere que haga. Advertir, romper la construcción cuando se utiliza algo. Existen numerosos tutoriales en la web sobre cómo escribir este tipo de código. Si desea generar un error cuando se compila (esto será molesto y hará que se elimine) o si se usa (algo más complejo de escribir).

Tenga en cuenta que todo esto implica cambiar las compilaciones para utilizar realmente el procesador de anotaciones.

¿Podrías mover todas las clases incompletas a un subpaquete llamado algo obvio como "NOTCOMPLETE"? Es un poco pirateado, pero podría ser lo suficientemente visible.

(Si no están todos en el mismo paquete, puedes recrear la estructura del paquete debajo).

No sé si realmente hay una buena manera de hacer esto en el código. Retrocede un paso:

Crea dos copias de todo el proyecto, una con la clase y otra sin. Marque la versión sin la clase como una base de código estable, lista para el lanzamiento de producción, y la versión con la clase como desarrollo para un lanzamiento futuro. Documente lo que debe suceder antes de que esta clase pueda considerarse calidad de producción.

Idealmente, debería hacer esto utilizando sucursales en la solución de control de origen que elija. Puede que tengas que hacer un poco de trampa, ya que parece que no has estado usando una estrategia de bifurcación. Quite con cuidado la nueva clase, ingrese una versión sin ella y realice algunas pruebas de regresión. Cuando esté satisfecho de que es estable, puede etiquetar esa revisión, crear una rama de desarrollo a partir de la etiqueta y luego agregar la clase nuevamente a la rama de desarrollo.

Optaría por hacer el resumen de la clase y comentar apropiadamente; de esa manera, el código todavía está allí como referencia, pero buena suerte para cualquiera que intente crear una instancia :)

¿Qué hay de hacer una dependencia que el compilador no puede resolver? Solo agrega:

importa this.is.not.done.yet.do.not.use.it;

a la parte superior. Los usuarios no podrán compilar con él.

Si desea probar la clase, simplemente cree un paquete / clase con ese nombre (o use uno más simple como "experimental.danger") y puede probar el nuevo código.