¿Cómo puedo crear un gancho git que me obligue a escribir comentarios javadoc?

¿Hay alguna forma de analizar de algún modo mis files de código java y search los comentarios del documento java? Quiero asegurarme de haber escrito javadocs para la class y cada método de la class (o todo en realidad). es posible?

Una seria falta de respuesta: no hagas esto. Explicaciones de opinión seguirán; pero toda mi información está enraizada en una gran cantidad de experiencia en torno a estos temas.

El punto es: tarde o temprano (¡más temprano!) Te encontrarás con situaciones en las que realmente quieres convertir tus cambios en git. Sabiendo que necesitas javadoc para hacerlo posible, comenzarás a poner contenido ficticio, como:

/** just to make the commit hook happy; @TODO: replace with real content */ 

Y te garantizo: tarde o temprano verás que tienes muchos de esos @TODOS pudriéndose en tu base de código durante días, semanas o meses. Porque al final, get esa nueva característica para el cliente que paga su salario es más importante que arreglar esos 15 @TODO que tiene en algún lado. ¿Dije 15? Ah, eso fue la semana pasada. Ahora tenemos 25 … (¡ La ley de LeBlanc más tarde nunca es igual ! ¡Garantizado!)

En otras palabras: si desea tener JavaDoc en todos los lugares, pero su disciplina no es "lo suficientemente buena" hoy para lograr eso sin ese tipo de aplicación; entonces eso conducirá a javadoc de baja calidad.

Más allá de eso: después de centrarme en las prácticas de "código limpio" durante varios años, creo que hoy: tener javadoc solo no es la respuesta. Aunque estoy trabajando en una gran empresa con equipos repartidos por todo el mundo.

De lo contrario. Cuando las personas están capacitadas para escribir código "legible", muy a menudo no necesitan ninguna (o solo partes diminutas) de javadoc para llegar allí. Debido a que sus layouts y habilidades para nombrar están en un nivel que el código se vuelve fácil de leer sin mucho javadoc.

Y si las personas no están entrenadas con respecto a esta habilidad, tienden a crear javadoc inútil. No puedo decirte con qué frecuencia le digo a las personas que desactiven esa plantilla de eclipse que crea una label @author totalmente inútil al generar una nueva class. Y adivinen qué: todavía hay innumerables ocurrencias de javacscs generados por eclipses … que nunca fueron tocados por ningún desarrollador después de ser generados.

Para resumir: necesita mucha disciplina y habilidad para crear javadoc útil . Si ya no tienes disciplina, entonces aplicar una regla de "algunos javadoc deben estar allí" no boostá la calidad de tu código.

Finalmente: no estoy diciendo que uno no deba analizar estas cosas por completo. Pero prefiero sugerir a

  1. definir directrices comunes sobre cómo se debe escribir javadoc; qué información es obligatoria; y qué tipo de elementos necesitan javadoc
  2. basado en eso, encuentre forms de verificar automáticamente
  3. para luego recostackr dicha información en una base regular (por ejemplo, durante construcciones nocturnas) y vigilar dichas statistics