CURSO DE JAVA

5 - los comentarios
Los programas de Java pueden tener dos tipos de comentarios: la aplicación comenta y comentarios
de la documentación. Los comentarios de aplicación son aquéllos encontrados en C++ por que se
delimita / *... * /, y / /. La documentación comenta (conocido como "el doc comenta") Java-sólo es,
y se delimita por / * *... * /. Doc comenta puede extraerse a archivos de HTML que usan la
herramienta del javadoc.

Se significan los comentarios de aplicación por comentar fuera el código o para los comentarios
sobre la aplicación particular. Se quieren los comentarios de Doc describir la especificación del
código, de una perspectiva aplicación-libre. para ser leído por diseñadores que necesariamente no
podrían tener a mano el código de la fuente.

Deben usarse los comentarios dar apreciaciones globales de código y proporcionar información
adicional que no está prontamente disponible en el propio código. Los comentarios deben contener
sólo información que es pertinente a leer y entender el programa. Por ejemplo, información sobre
cómo el paquete correspondiente se construye o en qué directorio que reside no debe ser incluido
como un comentario.

La discusión de nontrivial o nonobvious diseña las decisiones es apropiado, pero evita reproducir
información en que está presente (y aclara de) el código. Es demasiado fácil para los comentarios
redundantes salir de fecha. En evoluciona.

La nota:La frecuencia de comentarios a veces refleja calidad pobre de código. Cuando usted la
percepción compelió para agregar un comentario, considere volviendo a escribir el código para
hacerle el que despeja.

No deben adjuntarse los comentarios en cajas grandes dibujadas con asteriscos u otros carácteres.
Los comentarios nunca deben incluir los carácteres especiales como forma-alimente y retroceso.

5.1 Formatos de Comentario de aplicación

Los programas pueden tener cuatro estilos de comentarios de aplicación: bloquee, solo-línea,
arrastrando, y extremo-de-línea.

5.1.1 bloque Comenta

Se usan los comentarios del bloque para proporcionar descripciones de archivos, métodos,
estructuras de los datos y algoritmos. Pueden usarse los comentarios del bloque al principio de cada
archivo y antes de cada método. Ellos también pueden usarse en otros lugares, como dentro de los
métodos. Comentarios del bloque dentro de una función o el método debe dentarse al mismo nivel
como el código que ellos describen.

1
XCALIBURSYSTEM
 CURSO DE JAVA

Un comentario del bloque debe precederse por una línea pálida para ponerlo aparte del resto del
código.

/ *
* Aquí es un comentario del bloque.
* /

Los comentarios del bloque pueden empezar con que se reconoce por el indent(1) como el principio
de un comentario del bloque que no debe reformatearse. /*- El ejemplo:

/ * -

* Aquí es un comentario del bloque con algunos muy especial

* estructurando que yo quiero el indent(1) para ignorar.

* uno

* dos

* tres

* /

La nota: Si usted no usa el indent(1), usted no tiene que usar en su código o hacer cualquier otra
concesión a la posibilidad que alguien más podría ejecutar el indent(1) en su código. /*-

"La documentación Comenta" en página 9.

5.1.2 solo-línea Comenta

Los comentarios del calzón pueden aparecer en una sola línea dentada al nivel del código que sigue.
Si un comentario no puede escribirse en una sola línea, debe seguir el formato de comentario de
bloque (vea sección 5.1.1). Un comentario del solo-línea debe precederse por una línea pálida. Aquí
es un ejemplo de un comentario del solo-línea en el código de Java (también vea "la Documentación
Comenta" en página 9):

si (la condición) {

/ * El asa la condición. * /
...
}

5.1.3 Comentarios arrastrando

2
XCALIBURSYSTEM
 CURSO DE JAVA

Los comentarios muy cortos pueden aparecer en la misma línea como el código que ellos describen,
pero debe cambiarse bastante lejos para separarlos de las declaraciones. Si más de uno el comentario
corto aparece en un pedazo corto y grueso de código, ellos deben todos se dente a la misma escena
de la etiqueta.

Aquí es un ejemplo de un comentario arrastrando en el código de Java:

si (un == 2) {
el retorno VERDADERO; / * el caso especial * /
} el resto {
devuelva el isPrime(a); / * sólo trabaja para impar un * /
}

5.1.4 extremo-de-línea Comenta

Los delimiter del comentario pueden comentar fuera una línea completa o sólo una línea parcial.//
No debe usarse en las líneas múltiples consecutivas para los comentarios del texto; sin embargo,
puede usarse en las líneas múltiples consecutivas por comentar fuera las secciones de código. Los
ejemplos de todo los tres estilos siguen:

si (el foo> 1) {

/ / Haga un doble-capirotazo.
...
}
el resto {
el retorno falso; / / Explique por qué aquí.
}
/ /if (obstruya> 1) {
/ /

/ /...
/ /}
/ /else {
/ / el retorno falso;
/ /}

5.2 documentación Comenta

La nota: Vea "Java Fuente Archivo Ejemplo" en página 19 para los ejemplos de los formatos del
comentario describió aquí.

Para los detalles extensos, vea "Cómo Escribir los Comentarios de Doc para Javadoc" qué incluye la
información sobre las etiquetas de comentario de doc (@return, @param, @see):

http://java.sun.com/javadoc/writingdoccomments/index.html

Para los detalles extensos sobre los comentarios del doc y javadoc, vea la página de casa de javadoc
a:

3
XCALIBURSYSTEM
 CURSO DE JAVA

http://java.sun.com/javadoc/index.html

Los comentarios de Doc describen clases de Java, interfaces, constructores, métodos, y campos.
Cada comentario del doc es fijo dentro del delimiters del comentario, con un comentario por la
clase, interface, o miembro. /**...*/ Este comentario simplemente debe aparecer antes de la
declaración:

/ * *
* La clase del Ejemplo proporciona...
* /
el Ejemplo de la clase público {...

Nota que las clases cima-niveladas e interfaces no son dentadas, mientras sus miembros son. La
primera línea de comentario del doc (/ * *) para las clases y las interfaces no son dentadas; los doc
subsecuentes comentan linea cada uno tiene 1 espacio de sangrado (para encuadrar los asteriscos
verticalmente). Los miembros, incluso constructores, tienen 4 espacios para los primeros doc
comente línea y 5 espacios después de esto.

Si usted necesita dar la información sobre una clase, interface, variable, o método que no son
apropiado para la documentación, use un comentario de bloque de aplicación (vea sección 5.1.1)
(vea sección 5.1.2) comente inmediatamente después de la declaración. Por ejemplo, los detalles
sobre la aplicación de una clase deben entrar en semejante comentario de bloque de aplicación que
sigue la declaración de la clase, no en el comentario de doc de clase.

No deben posicionarse los comentarios de Doc dentro de un método o bloque de definición de

constructor, porque Java asocia los comentarios de la documentación con la primera declaración
después del comentario.

4
XCALIBURSYSTEM