Escrito el 11/04/2021
Buenas prácticas en el código: Comentarios
Los comentarios solo están justificados cuando no somos capaces de expresarnos con el código. En general, basta con escribir y encapsular todo en una función que se llame como lo que hay en el comentario.
Solo algunos comentarios son positivos:
- Comentarios legales, de derechos de autor
- Comentarios informativos de lo que devuelve una función, aunque también se pueden eliminar si en el nombre de la función especificamos lo que se devuelve
- Explicación de la intención, decisión tomada o advertencia
- Cuando utilizamos librerías de terceros, que no podemos modificar los nombres de funciones
- Comentarios TODO, aunque no deben ser excusa para dejar código incorrecto
- Comentarios en API públicas
Comentarios incorrectos:
Que dejan dudas en la explicación, redundantes, obligatorios, de registro de cambios (para ello está el control de código fuente), código comentado y comentarios sobre cosas que no están en el código adyacente.