Comentario de Java al final de la llave/bloque

Question

¿Es una práctica aceptada en el lenguaje de programación de Java finalizar una llave para un bloque de código con un comentario que explica brevemente qué bloque de código cierra la abrazadera? Personalmente, creo que son comentarios inútiles que complican la legibilidad del código, pero quizás podría estar equivocado. Por ejemplo:

public void myMethod(int foo) {  
    // some code 
    if (foo == 2) { 
     for (int i = 0; i < myMax; i++) { 
      while (true) { 
       // some more code 
      } // end while 
     } // end for 
    } // end if 
} // end myMethod(int) 

es la práctica de comentar bloques de código de manera similar una práctica aceptada?

Answer 1

Esto no es exactamente una mala práctica, PERO es un efecto secundario mortal de pobre práctica de codificación orientada a objetos!

Además, esto viola las pautas de estilo y los principios de "self-documenting code". Nunca debe tener tantos corchetes o un método lo suficientemente largo como para confundir al lector acerca de la ubicación del bracket, sino que debe encapsular esa funcionalidad en otro método que esté bien documentado.

Los corchetes implican bucles o cadenas lógicas if-else complejas, una buena práctica de programación es hacer que un método haga exactamente una cosa y hacerlo bien, luego construya su programa a partir de estos métodos más pequeños y atomizados. Leería la pieza seminal de Butler Lampson "Hints for Computer System Design". Va en algunos de los detalles sobre cómo diseñar un buen software.

Así que, esencialmente, no comentamos así porque:

1. Viola directrices de estilo
2. Muestra una mala programación orientada a objetos - atomizar su funcionalidad!
3. Es un efecto secundario mortal de la práctica que va en contra de los conceptos subyacentes de por qué se creó Java codificación - encapsulación, específicamente la ocultación de información
4. Viola el concepto de código de auto-documentado
5. Otros programadores harán que la diversión de tú.

Answer 2

Depende de qué tan complicado sea el método o la función. Al igual que si tiene algo que pueda leerse y entenderse fácilmente, no tendría sentido terminar CADA línea con un comentario que explique que la parte ha finalizado. Para eso sirven las sangrías y los saltos de línea. Sin embargo, si tiene algo que es verdaderamente complejo y afecta una parte importante de su código, debe indicar dónde termina ese código y qué hace esa sección.

Answer 3

Mi opinión es que, por lo general, NO es una buena práctica. Como siempre con las reglas, podría haber excepciones pero muy raras.

No es una buena práctica porque

1. editores modernos destacan el corchete de apertura cuando se coloca el cursor sobre la una y vice versa cierre.
2. Lo más importante: si existe la posibilidad de no ver el principio de la cláusula, significa que el método es enorme (más de media página), lo cual es una mala práctica.
3. Agrega ruido al código que confundirá a los lectores que están acostumbrados al estilo de codificación Java más convencional.
4. Incorporación LordScree-Joachim Sauer comentario: Estos comentarios serán dolor en el cuello para mantener. Por lo tanto, lo más probable es que no se mantenga y la información generalmente no estará sincronizada con la realidad.

Answer 4

Si hay bloques anidados del mismo tipo, puede ser confuso en lugar de hacerlo bien. Supongamos que tiene 4 o 5 declaraciones anidadas si (tenga en cuenta que esto es solo un ejemplo para demostrar la situación, independientemente de "oh debe separar esas" o "hacer un método" sugerencias) en ese caso tendrá 4 o 5 diferente // final si está secuenciado. Después de un tiempo, te hace confundir qué "fin si" es para qué enunciado, te hace gastar un esfuerzo extra inconscientemente para ver a través del código/enunciados reales porque no siempre es tan limpio/corto como tu ejemplo.

Answer 5

IMO, no ayuda mucho. El código dentro de un bucle o una declaración if no debe ser demasiado grande. Hubiera ayudado si hubiera 500 líneas dentro del ciclo.

Answer 6

Solo hago esto cuando hay un lugar en el código que tiene un montón de llaves de cierre después de la otra. Pero no para cada llave. Principalmente, parece que lo uso para bucles para que pueda ver fácilmente lo que es un bloque de código repetido.

Algo que se parece a esto:

 
      // ... 
      file.Close(); 
      } 
     } 
     } 
    } 
    } 
} 

entonces ayuda a añadir algunos comentarios:

 
      // ... 
      file.Close(); 
      } 
     } 
     } 
    }//for: each file 
    } 
}