¿Por qué es malo el comentario de estilo multilínea '//' (en Java)?

Question

http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html#286

que estaba leyendo la sección anterior de Java convenciones de codificación y comenzó a preguntarse por qué se dice "// comentario ..... no debe ser utilizado en múltiples líneas consecutivas de texto comenta"

copia pegada la sección relevante aquí por conveniencia:

el delimitador de comentario // puede comentar a cabo una línea completa o sólo una línea de parcial. No debe usarse en líneas consecutivas para texto comentarios; sin embargo, se puede usar en líneas consecutivas para comentando secciones de código.

¿Hay alguna razón racional para esto?

Answer 1

Hace que modificar y formatear los comentarios largos sea extremadamente doloroso.

La mayoría de los editores ofrecen algún tipo de función de envoltura para ajustar automáticamente el texto en líneas de longitud legible. Si cada línea comienza con un '//', se moverán, luego se eliminarán y se volverán a insertar los nuevos. Todo ese trabajo tedioso se puede evitar usando comentarios de estilo '/ * * /.

Answer 2

Incluso comentar una gran cantidad de código con // puede ser bastante horrible a veces.

utilizo Eclipes y aunque me gusta mucho la monotonía que lleva a cabo la programación de todos los días hay alguna combinación característica que puede dar resultados extraños ... por ejemplo ..

seleccione gran bloque de código que ya contiene algunos // código comentado multilínea, presione ctrl-/y coméntelo todo, luego haga ctrl-shift-f para formatear su código, si por alguna razón su formateador trata con comentarios, formateará su código. A continuación, vuelva a seleccionar todo y descomente con ctrl-/otra vez ...

algunas opciones de formato simplemente atornillarán el código comentado y lo retransmitirán, cuando lo eliminen, todo el infierno rompe loos y tendrá para analizarlo y reformatearlo manualmente.

Admito que esto es anecdótico, desde entonces he reconfigurado eclipse para no hacer esto más, pero también me abstengo ahora de usar // para un ancho de comentario de código tan grande a favor de/* * /. Sin embargo, hay muchas otras opciones que son mejores de usar:

/** para el comentario de Javadoc */de esta manera se puede acceder a los comentarios en el código completo, documentación, etc. ... comentar una vez, usar en todas partes.

Si sabe que va a crear un comentario de varias líneas que no es un documento de Java, entonces comenzando con/* el IDE se encargará del resto en cuanto al formateo. Entonces para explicar algoritmos raros de parcheo en el código usaré/* */en vez de //. Lo guardo para el trazador de líneas individual cuando es necesario.

Mi 2 céntimos

Answer 3

Siempre he pensado que eran necesarios los comentarios/* */estilo de comentarios de varias líneas, porque se permitió // "en múltiples líneas consecutivas para comentar las secciones de código." Las herramientas de formato de código deben poder distinguir fácilmente los comentarios de varias líneas del código comentado.

Si le dice a una herramienta de formato de código (o su IDE) que limpie su archivo, es probable que desee volver a envolver los comentarios de varias líneas al margen, envolviendo los espacios. No sería lo que la herramienta para envolver código comentado de esta manera. Dicho todo esto, muchas reglas de estilo son al menos ligeramente arbitrarias, por lo que puede no haber una razón importante por la cual se requirieron Convenciones de código para el Lenguaje de programación Java/* /comentarios de estilo para comentarios de varias líneas. En su lugar, podrían haber decidido utilizar/ */comentarios de estilo solo para comentar el código, y usar // comentarios de estilo para comentarios de una sola línea o múltiples líneas.

Answer 4

La idea es que un comentario de texto de líneas múltiples es una entidad, que lógicamente queremos mantener juntos. Los saltos de línea en dicho comentario no son más que lugares para envolver el texto, por lo que dividirlo en muchos comentarios "separados" no tiene sentido. Por lo tanto, construyes un solo bloque de comentarios alrededor de todo, usando/* * /.

Para comentar el código, cada línea es su propia unidad lógica, por lo que el uso de "//" s consecutivos es correcto, a veces. Esto es especialmente cierto si las líneas individuales se pueden comentar "en" por alguna razón, pero no todas. Sin embargo, si desea comentar un código de bloque completo en el que nunca tendrá sentido comentarlo parcialmente, es posible que prefiera usar/* */- de nuevo para agrupar todo de forma lógica y visual.

Answer 5

Diré que no lo llamaría "malo". Realmente, es una cuestión de convención, que es lo que otros han dicho. No hay nada intrínsecamente malo al respecto, excepto que puede hacer que los comentarios multilínea sean un poco más frustrantes (con las teclas) para trabajar.

Honestamente, creo que es un estándar doble con javadoc. Javadoc requiere:

/** 
* Validates a chess move. Use {@link #doMove(int, int, int, int)} to move a piece. 
* 
* @param theFromFile file from which a piece is being moved 
* @param theFromRank rank from which a piece is being moved 
* @param theToFile file to which a piece is being moved 
* @param theToRank rank to which a piece is being moved 
* @return   true if the chess move is valid, otherwise false 
*/ 

y yo no entiendo por qué la repetida "*" es mejor que "//". Por lo tanto, para mí, no hay nada inherente en que // sea malo (porque los editores pueden configurarse para agregarlos automáticamente a comentarios de varias líneas) y solo es una práctica común y convencional.

Answer 6

En realidad, he estado usando // para líneas múltiples durante años y nunca he tenido ningún problema grave con él. No soy un gran fan de /*...*/ más porque se obtiene:

/* I'm commenting out all this code for a moment 
    ... 
    /* And here is a multi line comment 
    that was hidden in the middle */ 
    ... 
*/ 

Gracias al compilador que se molesta y me dice del problema.

Donde como:

... 
// And here is a multi line comment 
// that was hidden in the middle 
... 

se convierte con una sola macro:

// ... 
// // And here is a multi line comment 
// // that was hidden in the middle 
// ... 

y está felizmente invertida con otra sola macro que devuelve de nuevo a la forma original

y en cuanto a :

// but now you have 
    // trouble edditing 
    // your comments so 
    // that every line 
    // is of equal size 

digo:

// Tough, this is a piece of code not a 
    // published novel 
    // and if varying lengths 
    // make 
    // it hard for you to read then heaven 
    // forbid how you handle the code 

Y no te odio edditing:

/****************************************************************** 
* Program: Foo.java            * 
****************************************************************** 
* Author: Codey Art Work          * 
* Purpose: To do something with something and get something not * 
*   forgetting something else.       * 
****************************************************************** 
* Revision History:            * 
****************************************************************** 
* Date | Author |            * 
*--------|--------|----------------------------------------------* 
* 1/2/09 | Jack | Now I have to keep all my comments in this * 
*  |  | tiny little space and if I edit it I just go * 
*  |  | aaarrrrrrggggggggggghhhhhhhhhhh!!!!!!!!!!!!! * 
******************************************************************/ 

que parecen siempre a aparecer en lugares que insisten en /* */ sobre //

_{y me Solo quiero decir a los chicos de Stack Overflow, este es un editor genial. Hacer muestras de código es muy fácil.}

Answer 7

puede ser para formatear el código de las cosas ... si hiciste el formateado automático (sangría) los códigos se verán feos.

En algunos editores de texto, los comentarios que utilizan /** ... **/ se pueden doblar por lo que será más fácil leer el código.

Answer 8

En mi experiencia, los siguientes estilos de comentarios ilustran por qué estoy de acuerdo con las Convenciones del Código de Java.

documentación Javadoc

/** 
* Description 
* @param foo refers to ... 
* @return true if... 
*/ 

Inglés comenta

/* 
* The sole reason for this unorthodox construct is just 
* to ... 
*/ 
synchronized(lockObject) { 
    foo = bar; 
} 

o

/* This is a single line comment */ 

Comentando código (prefiero no para el registro de código comentado).

// /* Accumulate the results */ 
// for (int i = 0; i < 10; i+=1) { 
//  bar += result[i]; 
// } 

¿Por qué?

Me gusta usar un ancho máximo en mis archivos de código. Eclipse hace un buen trabajo al refluir/* */bloquear comentarios para justificar con su comentario la configuración del ancho de línea. Me gusta este comportamiento para el texto escrito en inglés. Los comentarios se actualizan con frecuencia y, de lo contrario, tendrías:

// This is a 
    // long broken up comment that has been edited multiple 
    // times 
    // and the developer was too lazy to fix the justification 

o tienes que corregir la justificación de forma manual.

Usted no quiere que vuelva a fluir Eclipse comentada código para utilizar //

En segundo lugar, puede resaltar un bloque de código y añadir y eliminar los comentarios // estilo del comienzo de cada línea.

Nota, siempre comienzo cada línea de un comentario en bloque con un *.El siguiente es sólo buscar problemas:

/* Accumulate the results */ 
/* 
for (int i = 0; i < 10; i+=1) { 
    /* comment broke the outer comment : Sigh! */ 
    bar += result[i]; 
} 
*/