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.

He leído muchos artículos y ha encontrado 3 tipos principales de estilos de comentarios de java.

  1. Comentario de una línea (// …..)
  2. Bloquear comentarios (/ * ……. * /)
  3. 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…!!!

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.

  • Cuándo elegir variables para declarar como estática final
  • Incorporar detalles de la versión en android APK
  • Herramientas para creaciones rápidas de diseño / interfaz?
  • Administrador de alarmas de Android
  • Biblioteca de Microsoft Office de Microsoft (.doc, .docx, .xls, .ppt, etc.)
  • OnBackPressed () Mejor práctica / rendimiento
  • Cómo determinar qué está ralentizando la aplicación para Android
  • cómo puedo agregar elementos a listview dinámicamente en android
  • ¿Qué pasó con android.provider.Telephony?
  • Campos estáticos en Android
  • Cómo cambiar los elementos de ArrayList en Es duplicado sin afectar a la original?
  • FlipAndroid es un fan de Google para Android, Todo sobre Android Phones, Android Wear, Android Dev y Aplicaciones para Android Aplicaciones.