Me gustaría comenzar mi respuesta con una cita hecha por Jeff Atwood en su publicación de blog El código te dice cómo, los comentarios te dicen por qué :
el mejor tipo de comentarios son los que no necesitas
También afirma que:
Primero debe esforzarse por hacer que su código sea lo más simple posible de entender sin depender de los comentarios como una muleta. Solo en el punto donde el código no se puede hacer más fácil de entender, debe comenzar a agregar comentarios.
Estoy totalmente de acuerdo y en este punto debo agregar que antes de que pueda comenzar a hacer el código lo más simple posible, hago que el código funcione y luego empiezo a refactorizar. Entonces, durante la primera ejecución antes de refactorizar, agregar por qué los comentarios ayudan mucho.
Por ejemplo, si usa 3 bucles anidados con tablas de hash bidimensionales para llenar una tabla de días de la semana mientras analiza datos, es muy fácil perder la noción de lo que hizo alguien o incluso usted mismo si no se observa durante algunas semanas y se refactoriza de repente.
[loop1]6oclock -> [loop2]Monday -> [loop3]stage 1 to 4
-> tuesday-> stage 1 to 4
...
-> Saturday -> stage 1 to 4
7oclock -> Monday-> stage 1 to 4
....etc.
La parte superior es un ejemplo de cómo funcionarían 3 bucles anidados antes de refactorizar.
También explicar algunas condiciones de la rama puede ayudar a comprender el código mucho mejor con lo que uno estaba pensando en el proceso:
// added a zero before the actual day in order for the days always to be 2 digits long.
if( actualDayFuture < 10 )
{
actualDayFuture = padIfSingleDigitDate(actualDayFuture);
}
Incluso el código simple y obvio funciona bien con los comentarios. Solo para hacer las cosas un poco más obvias, más claras o más fáciles de entender para los colegas e incluso para usted mismo en el mantenimiento del software.
Claro, xp afirma tener un código que se explica por sí mismo, pero ¿duele un comentario de una línea?
También encuentro que las siguientes reglas de este blog son muy útiles:
- Comprende el material antes de escribir
- Escribe como si tu audiencia fuera de cuarto grado
- Piensa en cómo los lectores podrían malinterpretarte
Cualquiera que tenga que volver a su propio código o alguien más o incluso el código heredado sabe que puede ser un dolor de cabeza. Entonces, en lugar de ser perezoso o tratar de ser un súper codificador al no comentar nada o muy poco, ¿por qué no hacer que su propio inseguro o alguno pobre, que tiene que mantener su código, haga que la vida futura sea mucho más fácil siguiendo las reglas citadas?
También se dudan muchas decisiones de programación tomadas durante las revisiones y no siempre está claro por qué algunas partes se escribieron tal cual, incluso si algunas secciones del código son vitales para que un programa funcione debido a un error importante que se encontró cuando el código se utilizó durante años . Entonces, para no aburrirlos completamente con un tl; dr cierre con una última cita de acmqueue :
La documentación previa, clara y extensa es un elemento clave en la creación de software que puede sobrevivir y adaptarse. Documentar con altos estándares disminuirá el tiempo de desarrollo, dará como resultado un mejor trabajo y mejorará el resultado final. Es difícil pedir más que eso de cualquier técnica.
There are many questions on whether comments are good or bad, but no one that addresses the specific question of what are good examples of comments that tell you WHY.
Si todos brindan un ejemplo válido, entonces todas son respuestas correctas. El formato de este sitio web es para facilitar un proceso de preguntas y respuestas donde no todas las respuestas son iguales.