method - Javadoc @author etiqueta buenas prácticas
javadoc java 8 example (4)
Diría que para la mayoría de los propósitos @author es ruido no deseado. El usuario de su API no debería, y probablemente no le importe, o desee saber quién escribió qué partes.
Y, como ya ha indicado, SVN ya posee esta información de una manera mucho más autorizada que la que puede ofrecer el código. Entonces, si yo fuera uno de los @author del equipo, siempre preferiría el registro de SVN e ignoraría el @author . Apuesto a que el código no se sincronizará con la realidad, sea cual sea la política que adoptes. Siguiendo el principio de No repetir, ¿por qué mantener esta información en dos lugares?
Sin embargo, si hay alguna razón burocrática o de política por la cual esta información DEBE incluirse en el código, ¿ha considerado actualizar automáticamente la etiqueta @author en el código al momento del registro? Probablemente puedas lograr esto con un gancho SVN. Por ejemplo, podría enumerar todos los desarrolladores que cambiaron un archivo dado en el orden en que lo cambiaron; o quién lo cambió más; o lo que sea. O bien, si el @author es obligatorio en el código (de origen) que libera al mundo exterior, podría considerar agregar el @author automáticamente como parte de la compilación de lanzamiento (sospecho que podría obtener esta información de SVN de alguna manera).
En cuanto a agregar más de una sola etiqueta @author nivel de clase (u otro comentario), diría que estarías acumulando mucho ruido inútil. (De nuevo, tienes SVN).
En mi experiencia, es mucho más útil identificar un cambio histórico (por ejemplo, un cambio en una línea de código o un método), luego averiguar qué conjunto de cambios se relaciona con esto (y qué ticket de seguimiento). Luego tiene el contexto completo para el cambio: tiene el boleto, el conjunto de cambios, puede encontrar otros conjuntos de cambios en el mismo boleto, o al mismo tiempo, puede encontrar boletos relacionados, y puede ver TODOS los cambios que formó esa unidad de trabajo. Nunca vas a obtener esto de la anotación o comentarios en el código.
Me pregunto acerca de las mejores prácticas al crear Javadocs. Tengo un proyecto con muchos archivos. El código ha sido creado por muchos desarrolladores. Cada archivo tiene una anotación @author , por lo que es obvio quién ha creado una clase en particular.
Pero cuando algún otro desarrollador agrega un nuevo código a un archivo, lo modifica, etc., ¿cómo debe informar al resto del equipo que ha creado alguna función nueva o ha modificado un código existente? En otras palabras, ¿cómo deberíamos "mantener los Javadocs compatibles con la realidad"? ;)
- Añadir su nombre a la etiqueta
@authorexistente? Entonces, es más fácil identificar a quién preguntar en caso de dudas. - Agregue una etiqueta
@authora cada nuevo método, clase interna, etc.?
Por supuesto, dado que usamos SVN, es fácil investigar quién hizo qué, pero para mantener las cosas claras, este material de Javadoc también debe tenerse en cuenta.
¿Cuál es la mejor manera de usar estas etiquetas @author ?
En proyectos realmente grandes y de larga ejecución con muchos desarrolladores, es útil saber si ho es responsable del código dado, quién puede proporcionarle información adicional y demás. En ese caso, sería útil tener dicha información en el archivo usando @author tag. No marca quién creó el archivo o quién hizo algunas contribuciones importantes, pero quién es una persona de contacto para ese código. Es posible que esas personas sean muy diferentes, ya que el autor original puede estar ya en un proyecto diferente o haber abandonado la empresa hace años.
Creo que en un gran proyecto ese enfoque puede ser útil, sin embargo, hay una advertencia. Mantener la información del autor de cada archivo es muy difícil ya que hay una gran cantidad de archivos y tarde o temprano fallarán. Cada vez más archivos tendrán información obsoleta y los desarrolladores ya no confiarán en este @author como fuente de información y lo ignorarán.
La solución, que puede funcionar, no es mantener @author en cada archivo, sino solo por módulo (paquetes de alto nivel). Javadoc tiene una función, donde puede documentar no solo archivos sino paquetes completos ( consulte esta pregunta para obtener más detalles ).
Sin embargo, este es un caso especial y siempre que su proyecto no sea tan grande o viejo, recomiendo omitir la información del autor.
Es posible que desee considerar por qué quiere etiquetas de autor en la fuente. La Fundación Apache no y yo estoy de acuerdo.
http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags
A mi entender, esta es una forma de trabajo de culto a la carga desde cuando las fuentes se imprimieron en papel. Con los modernos sistemas de control de versiones, esta información y más se puede encontrar en la historia de todos modos.
Puede tener más de una etiqueta @author . En caso de que realice cambios importantes en una clase, simplemente agregue una nueva etiqueta @author con su propio nombre. No es necesario marcar los cambios que ha realizado o poner su nombre en los cambios, ya que el historial de revisiones debería poder mostrarlo con claridad.