Esta publicación es la continuación de la anterior publicación: Comentarios - Clean code - Parte 1
Comentarios confusos
En ocasiones habrá
comentarios que no sean lo suficientemente precisos y provoquen que
el lector termine finalmente leyendo el código para averiguar el
porqué de ese comportamiento distinto al expresado.
En el siguiente
ejemplo cualquier programador se extrañaría al descubrir que se
están añadiendo «likes» al usuario.
Comentarios obligatorios
No tiene ningún
tipo de sentido incluir comentarios obligatorios sólo porque haya
una regla que lo indique o porque el IDE los proporcione
automáticamente. Estos comentarios no aportan valor, ensucian el
código y lo hacen más confuso, ya que los lectores no distinguen
los comentarios con valor de aquellos que carecen de él.
Comentarios periódicos
Hace tiempo, cuando
los controladores de versiones estaban menos evolucionados, se usaban
para llevar un registro de los cambios añadiendo estos a un
comentario al comienzo del fichero. Afortunadamente hoy en día no es
necesario por lo que deberían desaparecer.
Comentarios sin valor
Los comentarios
generados automáticamente por un IDE son comentarios sin valor que
muestran lo que es obvio.
Debido a esto, el
lector aprende a ignorar estos comentarios pasándolos por alto y,
por lo tanto, esto puede llegar a hacer ignore comentarios que sí
aporten algo sustancial.
Los comentarios que
no aportan nada suelen derivar de la producción de un mal código
por parte de un programador que, en lugar de invertir tiempo en
redactar el comentario, debería haber limpiado el código.
Comentarios sin valor, copiados y pegados
En ocasiones, cuando
se copia y pega un código se incluyen los comentarios en la copia.
Una vez actualizado el código los comentarios pueden no actualizarse
correctamente por lo que el lector tendrá que perder tiempo en
entender lo que está leyendo.
En el siguiente
ejemplo se puede observar como la variable «$address»
presenta un comentario con un nombre distinto, lo que obliga al
lector a leer varias veces el código hasta comprender que el
comentario está mintiendo.
No usar un comentario cuando se puede usar una función o una variable
En determinadas
ocasiones se podrá refactorizar el código de una manera que exprese
lo mismo que el comentario.
Podría
refactorizarse de la siguiente manera:
Marcadores de posición
Los marcadores de
posición se usan para llamar la atención del lector en una parte
del archivo.
Esto rara vez aporta
valor por lo que se deberían evitar.
Comentario después de cerrar llaves
De nuevo, cuando no
había control de versiones, podría haber tenido algún sentido. En
un futuro, este código comentado permanecerá ahí ya que si quien
lo redactó no lo borró es que tendría alguna buena razón, por lo
tanto, los programadores siguientes no lo borrarán tampoco. Un
ejemplo:
Atribuciones
Los comentarios que
son atribuciones no tienen ningún sentido con los controles de
versiones actuales.
Comentar código obsoleto
De nuevo, cuando no
había control de versiones, podría haber tenido algún sentido. En
un futuro, este código comentado permanecerá ahí ya que si quien
lo redactó no lo borró es que tendría alguna buena razón, por lo
tanto, los programadores siguientes no lo borrarán tampoco. Un
ejemplo:
Si el cálculo del
valor de un post ha cambiado no debería existir código que no fuera
útil.
Comentarios HTML
Se desaconseja
añadir HTML en un comentario del código fuente para que alguna
herramienta lo muestre. Debería ser la propia herramienta la que lo
interprete y lo maquete.
Comentarios sobre código no cercano
Los comentarios
deben añadir información sobre el código cerca de donde aparece.
Por lo tanto, debe evitarse presentar información de otras partes
del sistema.
En el siguiente
ejemplo se añade el puerto por defecto para conectar con la base de
datos pero, en un futuro, podría cambiar dicho puerto y el
comentario permanecería.
Comentarios con demasiada información
Son comentarios que
aportan información irrelevante para el funcionamiento del sistema.
Añadir el RCF para la especificación de un email para una función
que valide un email es un exceso de información.
Comentarios que no son obvios
Cuando un lector se
encuentra un comentario este debe describir la intención del código.
Si el propio comentario necesita un comentario para entenderse. el
fallo de expresión del programador es completo, lo que obliga al
lector a leer el mal código.
En el siguiente
ejemplo observamos el cálculo de una publicación. El valor inicial
es 0 pero si esta publicada y filtrada se realiza el cálculo de otra
manera. Cuando el lector se encuentra la función «isNotFilter»,
esta no proporciona ningún tipo de intención ya el lector desconoce
el significado de «no estar filtrado» y se verá obligado así a
leer esa función para entender su intención.
Cabeceras de funciones
Si se sigue la regla
que especifica que cada función debe tener un solo cometido, siendo
esta lo suficientemente corta y nombrada adecuadamente, los
comentarios de cabecera no aportan ningún valor.
La documentación es
útil para las API que van a ser públicas. Incluir este tipo de
documentación para la parte privada del código no suele ser útil,
ya que es, a menudo, más una distracción que una ayuda.
No hay comentarios:
Publicar un comentario