Los comentarios siempre son fallos.
Debemos usarlos porque no siempre sabemos como expresarnos sin ellos, pero su uso no es motivo de celebración.
Cuando tenga que escribir uno, piense si no hay otra forma de de expresarse en código.
La energía empleada en escribir comentarios y mantenerlos actualizados, debería emplearse en crear un código más descriptivo, claro y expresivo.
Solo el código puede contar lo que hace. Es la única fuente de información precisa.
El código claro, expresivo y sin apenas comentarios, es muy superior al código enrevesado, complejo y lleno de comentarios.
No usar comentarios, use funciones o variables
Muchas veces para explicar nuestras intenciones, basta con crear una función que diga lo mismo que el comentarios que pensaba escribir.
Comentarios al cerrar Estructuras
Los comentarios al cerrar las llaves para marcar que estructura esta cerrando, se suelen usar en funciones extensas. Pruebe a reducir el tamaño de su función.
Fragmentos de codigo comentado
No deje código comentado, los lectores que vean el código no tendrán valor de borrarlo. Por eso, pensaran que esta ahí por algo y que es demasiado importante para borrarlo.
Posibles casos de utilización correcta de comentarios:
- Explicar intenciones: Explicar el por que se llego a esa decisión de implementación en el código.y no a otra.
- Advertir las consecuencias: Advertir a otros programadores posibles consecuencias al modificar el código.
- Amplificación: Para amplificar la importancia de al que, en caso contrario, parecería irrelevante.
Contexto del comentario
Si tiene que escribir comentarios, que sea del código que le rodea. No escriba información global del sistema en el contexto de un comentarios local.
Superfluo de información
No incluya en sus comentarios reflexiones históricas ni irrelevantes descripciones de detalles.
Comentarios TODO
TODO son tareas que el programador piensa que debería haber hecho pero no es así. Pueden ser:
- Un recordatorio para eliminar una función obsoleta.
- Una solicitud para buscar un nombre más adecuado.
- Para marcar un cambio que dependa de un evento planeado.
Muchos IDE cuentan con funciones especiales para localizar comentarios TODO.
No colapse el código con estos comentarios, examínelos y elimine todos los que pueda.