Código Java que comenta las mejores prácticas
He finalizado mi proyecto Java / Android y ahora tengo que comentar los códigos (principalmente clases y métodos importantes).
Tengo que hacerlo siguiendo los mejores estándares industriales como más tarde si alguien más necesita modificar, debe ser bien staright adelante.
- Cómo comparar la hora actual con el tiempo almacenado en la base de datos en Android
- Errores de json-parsing en tiempo de ejecución
- Archivos bajo la carpeta de compilación se generan y no se deben editar, no se puede volver a generar el proyecto de android
- SetX (), setTranslationX (), setY () y setTranslationY ()
- Descifrar el archivo cifrado AES en C # con java
He leído muchos artículos y ha encontrado 3 tipos principales de estilos de comentarios de java.
- Comentario de una línea (// …..)
- Bloquear comentarios (/ * ……. * /)
- Comentarios del Doc (/ ** ……. * /)
He leído principalmente sobre la opción 2 y 3. Las discusiones de desbordamiento de pila
Así que pensé en ir con la segunda opción, ya que no es necesario para generar documentos HTML como estas clases no van a utilizar por cualquier otra gente y esta es la aplicación de esta aplicación.
Me pregunto cuáles son las mejores prácticas en el bloque de comentarios indicando "retorno" tipo, "parámetros" y "bref descripción" del método o clase.
Quisiera escuchar las mejores prácticas estándar industriales del código java comentando.
Gracias por adelantado…!!!
- ¿Cómo implemento un observador para obtener datos de un oyente?
- ¿Puedo configurar el tiempo de espera de getaddrinfo en Android para DefaultHttpClient?
- Android Studio: No se pudo crear MD5 HashFile
- Error en la verificación de la firma de Android LVL
- Uso de fuentes tipo otf en el estudio de Android
- ¿Cuáles son las implicaciones de portabilidad de usar el NDK?
- ¿Hay una manera rápida de reconocer códigos HTML ASCII en una cadena o TextView?
- Establecer márgenes en un LinearLayout programáticamente
Yo recomendaría ir con la tercera opción, porque si alguien mira su código por ejemplo a través de un IDE que apoya el JavaDOCs (por ejemplo, Eclipse), mostrará información relevante sobre los objetos que examina cuando él / ella asoma sobre un elemento que le interesa.
De esta manera, el desarrollador no tendrá que abrir el archivo fuente de la clase real para entender qué es el contrato, qué hace, o quizás qué excepciones tiene que vigilar al usarlo.
Puede vincular clases / métodos relevantes a través de ganchos JavaDOC como @ see.
Personalmente, por lo general me gusta poner comentarios DOC por lo menos en mi clase, y los métodos públicos, para los métodos privados que no suelen ver mucho uso de los comentarios DOC ya que no suelen generar el HTML JavaDOC. Aparte de los comentarios de DOC, normalmente suelo usar los comentarios de una sola línea, y sólo uso comentarios de bloque cuando siento que una frase no será suficiente para expresar lo que quería o cuando las restricciones de margen de impresión entran en juego.
Para obtener explicaciones sobre el uso de API javadoc / ** … * /
Para explicaciones dentro del código use //
Para comentar varias líneas de código use / * … * /
Utilice el estándar Javadoc con las convenciones de etiquetas javadoc (tercera opción). Por qué:
- Es un estándar utilizado widly que cada programa de Java debe entender fácilmente.
- La mayoría de los IDE admiten el estándar javadoc y las etiquetas. El IDE muestra información relevante y ayuda al desarrollador
- Si no necesita generar HTML ahora, tal vez necesite hacerlo más tarde.
- Es el "estándar industrial", como usted pide.
- Al describir clases y métodos, describe la API de su programa. El estándar para describir el API es Javadoc, así que úselo.
La primera y segunda opción es más para comentarios directamente en líneas de código. No para la descripción de las clases y métodos.
- Cómo evitar que SMS ingresen a la bandeja de entrada en Android Kitkat
- La consulta devuelve un cursor nulo