Esta publicación se
centra en el capítulo de Comentarios de Clean
Code (Robert
C. Martin).
Los comentarios son
una herramienta para transmitir conocimiento. Si estos se utilizan
con el fin de expresar de una manera más clara el propósito del
código, esto significará que no se está desarrollando un código
lo suficientemente comprensible y, por lo tanto, que la capacidad de
expresión del programador está fallando.
El uso de
comentarios no suele considerarse una buena práctica porque la
mayoría de las veces mienten, principalmente, porque quedan
desactualizados al no hacerse un mantenimiento de los mismos.
Es mejor no incluir
comentarios que incluir comentarios poco precisos, ya que estos
producen confusión en el lector. Lo único que es verdad siempre es
el propio código.
Los comentarios no compensan un mal código
Es mejor invertir el
tiempo en reescribir un mal código que en comentarlo.
Explicarse en el código
A veces resulta un
poco más difícil explicarse en el código, pero invertir algo de
tiempo y esfuerzo en tratar de explicar la intención del mismo
revierte en una mayor comprensibilidad.
Por ejemplo se puede
escribir:
Se puede evitar el
comentario invirtiendo tiempo en realizar una refactorización de la
condición que derive en la creación de una nueva función
«canUserEditAPost()» que comunique la intención de dicha
condición:
Comentarios útiles
Hay algunas
ocasiones en las que los comentarios son necesarios o beneficiosos
aunque no sea así por regla general.
Comentarios legales
A veces las empresas
fuerzan a escribir cierto tipo de comentarios por razones legales.
Comentarios informativos
En ocasiones, un
comentario informativo podría ser de utilidad si evita al lector
tener que decodificar algún código.
Por ejemplo, en el
caso de escribir una expresión regular que pueda llegar a ser
relativamente compleja, el comentario podría comunicar la intención
de esta sin que el lector tenga que invertir tiempo en comprender su
intención.
Explicación de la intención
En algunos casos, un
comentario brinda información útil sobre la implementación y la
intención detrás de una decisión. Es posible que no se comparta la
solución adoptada pero por lo menos se conoce la intención.
Por ejemplo, se
pueden comparar dos publicaciones y valorarlas.
Clarificación
A veces resulta útil
clarificar algo que es complicado de leer y convertirlo en algo más
comprensible aunque se corre el riesgo, como con cualquier
comentario, de caer en incorrecciones, por lo que siempre es
recomendable tratar de buscar una alternativa.
Advertencia de consecuencias
A veces es útil
advertir a otros programadores de alguna consecuencia.
Hay maneras más
seguras de no ejecutar ese test pero la intención es comunicar que,
cuando se utiliza, el servidor va sufrir una carga significativa que,
en el momento de escribir el comentario, saturaba el servidor.
Comentarios TODO
Los comentarios TODO
son comentarios sobre cosas que los programadores piensan sobre cómo
debería estar hecha una cosa pero por alguna razón no se pudo
hacer. Podría ser un recordatorio para borrar alguna función que
esté obsoleta, una nota para mejorar la implementación cuando el
tiempo lo permita, o un cambio que depende de una decisión que aún
no está tomada.
Un TODO no debería
ser una excusa para dejar un mal código en el sistema.
Amplificación
Un comentario podría
amplificar la importancia de algo que, a priori, podría parecer más
trivial.
Documentación
La documentación en
las cabeceras de los métodos es muy útil si hay una API pública
que mantener. En el caso contrario, la documentación es como
cualquier otro tipo de comentario que puede no estar mantenido.
Comentarios malos
La mayoría de los
comentarios son de este tipo, ya que suelen ser declaración de
intenciones para un código que no es capaz de expresarse
adecuadamente.
Inútiles
Son aquellos
comentarios a los que el autor, incapaz de transmitir la intención
ni a través de estos, no ha dedicado suficiente tiempo.
En este caso parece
que, si se produce una excepción, los valores por defecto ya están
cargados pero surgen dudas al respecto: ¿dónde se cargan esos
valores por defecto? ¿El fichero de configuración en la ruta
«$pathToConfig» no es el fichero por defecto? ¿Por qué el
autor deja el catch vacío? Al final parece que el único recurso
para conocer el funcionamiento real es examinar el código.
Cualquier comentario
que obligue a examinar el código para entender su significado es un
comentario inútil.
Comentarios redundantes
Son comentarios que
no aportan un valor real ya que se tarda más tiempo en leerlos que
en leer el código.
Todos los
comentarios generados automáticamente por un IDE tampoco aportan
valor real. En el caso siguiente se crean en la cabecera del método.
No hay comentarios:
Publicar un comentario