Anotaciones sobre el libro Clean Code - 5

4 - comentarios

El comentario más valioso es aquel que no se tiene que escribir
NO comentar código incorrecto, es mejor reescribirlo
No hay nada más útil que un comentario en un lugar correcto, por otro lado, no hay nada peor que comentarios incorrecto
No hay nada más dañino que un comentario viejo que mienta y desinforme
Cuanto más viejo y alejado del código que describe, es mayor la probabilidad de que se equivoque
Son un mal necesario
Cuando escriba un comentario, piense si no existe otra forma de expresarlo a través del código
Un comentario impreciso es peor que la ausencia de comentario
Sólo el código dice la verdad respecto a lo que hace
un comentario es útil cuando clarifica contenido que no podemos modificar para mejorar (como el uso de cosas de bibliotecas externas)
Los comentarios TODO no son excusa para mantener código incorrecto
No usar comentarios si se puede usar una función o una variable clara en su lugar
Si se escribe un comentario, que describa el código que lo rodea, nunca información global fuera de contexto
La conexión entre un comentario y el código que describe debe ser evidente, si se molestó en escribir un comentario, al menos asegúrese que el lector entenderá su significado
Una función breve no requiere explicación y un buen nombre funciona mejor que un comentario en el encabezado

El código incorrecto es la principal motivación para crear comentarios
Un código claro y expresivo es mucho mejor a un código complejo con muchos comentarios, en lugar de invertir tiempo comentando código, resuélvalo

Aquellos por estándares corporativos, como los de derechos de autor (no son contratos legales. Cuando sea posible, refiérase a una licencia estándar o a un documento externo)

Son excusas de código pobre
Añadir un comentarios sin razón o por seguir el proceso es un error, si va a invertir tiempo en escribir comentarios, asegúrese de ser el mejor que puede redactar
Cualquier comentario que le obligue a buscar su significado en otro lugar, ha fallado en su comunicación y no merece los bits que consume
Un comentario redundante que explica funcionamiento al igual que el código, es un error
Un comentario confuso o impreciso pueden ser dolores de cabeza para el futuro
Comentarios de cambios (logs de cambios) eran necesarios antes del software de control de versiones, ahora son irrelevantes y deben ser eliminados
Comentarios de marcador de posición son atractivas si no se usan demasiado, de lo contrario terminarán ignorados. Usar cuando el beneficio es significativo
```
//     Event
////////////////////////////////
```
Los comentarios de cierre de función tienen sentido en funciones extensas, mejor pruebe a reducir el tamaño de las funciones