in

Convenciones de código para el lenguaje de programación Java: 5. Comentarios

5 – Comentarios

Los programas Java pueden tener dos tipos de comentarios: comentarios de implementación y comentarios de documentación. Los comentarios de implementación son los que se encuentran en C ++, que están delimitados por /*…*/ y //. Los comentarios de documentación (conocidos como «comentarios de documentos») son solo de Java y están delimitados por /**…*/. Los comentarios de los documentos se pueden extraer a archivos HTML utilizando la herramienta javadoc.

Los comentarios de implementación están pensados ​​para comentar el código o para hacer comentarios sobre la implementación en particular. Los comentarios de los documentos están destinados a describir la especificación del código, desde una perspectiva sin implementación. para ser leído por desarrolladores que no necesariamente tengan el código fuente a mano.

Los comentarios deben utilizarse para ofrecer una descripción general del código y proporcionar información adicional que no esté disponible en el código en sí. Los comentarios deben contener solo información que sea relevante para leer y comprender el programa. Por ejemplo, la información sobre cómo está construido el paquete correspondiente o en qué directorio reside no debe incluirse como comentario.

La discusión de decisiones de diseño no triviales o no obvias es apropiada, pero evite duplicar la información que está presente en (y clara) en el código. Es demasiado fácil que los comentarios redundantes se queden obsoletos. En general, evite cualquier comentario que pueda quedar desactualizado a medida que evoluciona el código.

Nota:La frecuencia de los comentarios a veces refleja la mala calidad del código. Cuando se sienta obligado a agregar un comentario, considere volver a escribir el código para que sea más claro.

Los comentarios no deben incluirse en recuadros grandes dibujados con asteriscos u otros caracteres.
Los comentarios nunca deben incluir caracteres especiales como avance de formulario y retroceso.

5.1 Formatos de comentarios de implementación

Los programas pueden tener cuatro estilos de comentarios de implementación: bloque, línea única, final y final de línea.

5.1.1 Bloquear comentarios

Los comentarios de bloque se utilizan para proporcionar descripciones de archivos, métodos, estructuras de datos y algoritmos. Los comentarios de bloque se pueden utilizar al principio de cada archivo y antes de cada método. También se pueden usar en otros lugares, como dentro de los métodos. Los comentarios de bloque dentro de una función o método deben tener sangría al mismo nivel que el código que describen.

Un comentario de bloque debe ir precedido de una línea en blanco para diferenciarlo del resto del código.

/*
 * Here is a block comment.
 */
         

      

/*- sangrar

/*-
 * Here is a block comment with some very special
 * formatting that I want indent(1) to ignore.
 *
 *    one
 *        two
 *            three
 */
  
      

    

Nota: sangría /*- sangrar

Ver también «Comentarios sobre la documentación» en la página 9.

5.1.2 Comentarios de una sola línea

Los comentarios breves pueden aparecer en una sola línea con sangría al nivel del código que sigue. Si un comentario no se puede escribir en una sola línea, debe seguir el formato de comentario de bloque (ver sección 5.1.1). Un comentario de una sola línea debe ir precedido de una línea en blanco. A continuación, se muestra un ejemplo de un comentario de una sola línea en código Java (consulte también «Comentarios sobre la documentación» en la página 9):

if (condition) {

    /* Handle the condition. */
    ...
}

5.1.3 Comentarios finales

Los comentarios muy breves pueden aparecer en la misma línea que el código que describen, pero deben desplazarse lo suficiente para separarlos de las declaraciones. Si aparece más de un comentario breve en un fragmento de código, todos deben tener sangría en la misma configuración de pestaña.

A continuación, se muestra un ejemplo de un comentario final en código Java:

if (a == 2) {
    return TRUE;            /* special case */
} else {
    return isPrime(a);      /* works only for odd a */
}

5.1.4 Comentarios de fin de línea

los // El delimitador de comentarios puede comentar una línea completa o solo una línea parcial. No debe usarse en varias líneas consecutivas para comentarios de texto; sin embargo, se puede utilizar en varias líneas consecutivas para comentar secciones de código. A continuación se muestran ejemplos de los tres estilos:

if (foo > 1) {

    // Do a double-flip.
    ...
}
else {
    return false;          // Explain why here.
}
//if (bar > 1) {
//
//    // Do a triple-flip.
//    ...
//}
//else {
//    return false;
//}

5.2 Comentarios sobre la documentación

Nota: Ver «Ejemplo de archivo de origen Java» en la página 19 para ver ejemplos de los formatos de comentarios descritos aquí.

Para obtener más detalles, consulte «Cómo escribir comentarios de documentos para Javadoc», que incluye información sobre las etiquetas de comentarios de documentos (@return, @param, @see): Enlace

Los comentarios de documentos describen clases, interfaces, constructores, métodos y campos de Java. Cada comentario de documento se establece dentro de los delimitadores de comentarios. /**...*/, con un comentario por clase, interfaz o miembro. Este comentario debería aparecer justo antes de la declaración:

/**
 * The Example class provides ...
 */
public class Example { ...

Tenga en cuenta que las clases e interfaces de nivel superior no tienen sangría, mientras que sus miembros sí lo están. La primera línea del comentario de documento (/ **) para clases e interfaces no tiene sangría; las siguientes líneas de comentarios de documentos tienen 1 espacio de sangría (para alinear verticalmente los asteriscos). Los miembros, incluidos los constructores, tienen 4 espacios para la primera línea de comentario del documento y 5 espacios a partir de entonces.

Si necesita proporcionar información sobre una clase, interfaz, variable o método que no es apropiado para la documentación, use un comentario de bloque de implementación (ver sección 5.1.1) o de una sola línea (ver sección 5.1.2) comenta de inmediato después la declaracion. Por ejemplo, los detalles sobre la implementación de una clase deben incluirse en dicho comentario de bloque de implementación. siguiente la declaración de clase, no en el comentario del documento de clase.

Los comentarios de documentos no deben colocarse dentro de un bloque de definición de método o constructor, porque Java asocia los comentarios de documentación con la primera declaración después el comentario.

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

1UlGNrKMSUAqzbqxvxjGcDA

Cálculo de normas P vectoriales – Álgebra lineal para ciencia de datos -IV

Listas de Python