Existen 2 tipos de programadores, los que están a favor de escribir comentarios el código y los que están en contra. Yo era de los primeros, hasta que leí este capítulo, por lo que si eres un enamorado de los comentarios sigue leyendo bajo tu responsabilidad.
Don’t comment bad code—rewrite it.
No hay nada tan útil como un comentario bien colocado, ni nada puede hacer tanto daño como uno que propague mentiras. Los comentarios no son buenos ni malos en sí, son solo una herramienta para explicar lo que no hemos sido capaces de expresar mediante el código. Es un claro indicador de que deberíamos haber escrito un código más legible, pero no hemos sido capaces de hacerlo. Son en el mejor de los casos un mal necesario, no un motivo de celebración (un buen comentario solo indica un gran esfuerzo por explicar un mal código). Cuando te veas en la necesidad de escribir un comentario párate a pensar si no sería mejor reescribir el código en vez.
¿Por qué tanta aversión? Si solo son un pequeño texto que ayuda a entender mejor el código, no pueden ser tan malos. El motivo principal es que no se pueden mantener fácilmente. Es muy fácil que un comentario se vaya perdiendo y quedando obsoleto. ¿Quien no ha reescrito un código y se ha olvidado de actualizar su comentario? ¿O no ha entendido un comentario escrito por otro y lo ha dejado ahí «por si acaso»?
Al final acaba ocurriendo que el comentario y el código no dicen lo mismo, y ¿a quien hacemos caso? ¿A un código que hay que pararse a entender e interpretar o a unas líneas fáciles de entender?
Aunque el equipo sea disciplinado y mantenga los comentarios, supone un esfuerzo y se conseguiría lo mismo escribiendo un buen código ¿por qué no hacerlo directamente?
Aun así, hay momentos en los que tiene sentido escribir un comentario, simplemente hay que reducirlos al mínimo.
Los comentarios no compensan el mal código
Una de las motivaciones más comunes para escribir comentarios es un código incorrecto. En lugar de dedicar tiempo a comentar un código desordenado, es mejor dedicarlo a limpiar ese desorden. Un código claro y expresivo con pocos comentarios es muy superior a uno desordenado y complejo con muchos comentarios.
Escribe código autoexplicativo
En ocasiones el código es un mal vehículo para explicar algo, pero no quiere decir que nunca o rara vez sea un buen medio de explicación. ¿Cual de estas 2 opciones prefieres?
// Check to see if the employee is eligible for full benefits if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))
if (employee.isEligibleForFullBenefits())
Solo cuesta unos segundos escribir un código autoexplicativo, la mayoría de veces es suficiente con escribir una función que diga lo mismo que el comentario.
Buenos comentarios
Hay una serie de comentarios que el autor considera buenos o necesarios, aun así hace una aclaración: el único comentario bueno es aquel que encuentras una manera de no escribirlo.
Como veréis, la mayoría se pueden evitar de una manera u otra.
Comentarios legales
A veces necesitamos escribir ciertos comentarios por motivos legales, como el copyright al principio de cada archivo. Por suerte algunos IDEs ocultan estos comentarios para evitar que molesten.
Comentarios informativos
Hay comentarios que proporcionan información útil:
// Returns an instance of the Responder being tested. protected abstract Responder responderInstance();
Puede parecer interesante escribir un comentario así, pero realmente será siempre mejor renombrar el método para que transmita esta información: responderBeingTested.
// format matched kk:mm:ss EEE, MMM dd, yyyy Pattern timeMatcher = Pattern.compile( "\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");
En este caso nos permite conocer el comportamiento de la expresión regular. Pero sería más claro si la extraemos a una clase que convierta el formato de una fecha. Así sería innecesario el comentario.
Explicación de intención
En ocasiones, un comentario va más allá de la información útil y proporciona la intención detrás de una decisión. En el siguiente comentario, se explica que se considera que los objetos de la clase WikiPagePath van siempre antes en una ordenación porque son del tipo correcto.
public int compareTo(Object o) {
if(o instanceof WikiPagePath) {
WikiPagePath p = (WikiPagePath) o;
String compressedName = StringUtil.join(names, "");
String compressedArgumentName = StringUtil.join(p.names, "");
return compressedName.compareTo(compressedArgumentName);
}
return 1; // we are greater because we are the right type.
}
El autor no comenta nada más de este caso, parece que lo de por bueno, y que puedes estar de acuerdo o no con la decisión del programador que lo escribió, pero al menos sabes por qué tomó esa decisión. Personalmente no me gusta, los detalles de la implementación no deberían estar informados en un comentario perdido por el código. Donde esté un buen test (algo como WikiPagePath should be first), que se quiten estos comentarios.
Aclaración
A veces es útil traducir el significado de algún argumento o return poco claro en algo que sea legible. Es preferible darle un nombre mejor, pero en ocasiones no podemos hacerlo por tratarse de una librería externa o un código que no podemos modificar, puede ser útil un comentario.
El autor advierte del riesgo de que el comentario sea incorrecto, en el siguiente código se puede ver lo difícil que puede llegar a ser de comprobar:
Personalmente, no he vuelto a hacer esto desde que me enseñaron una técnica muy sencilla para darle un nombre a lo que no podemos renombrar: consiste en crear una función que devuelve lo mismo que recibe, que puede parecer una tontería, pero a la que si le podemos damos el nombre que queramos. O en este caso, se puede simplemente crear una serie de funciones:
Public Boolean isEqual(a, b) {
return a.compareTo(b) == 0
}
Public Boolean isNotEqual(a, b) {
return a.compareTo(b) != 0
}
…
Y reescribir el código como:
assertTrue(isEqual(a,a)); assertTrue(isNotEqual(a,b)); …
Lo que lo hace mucho más fácil de entender, quitando un nivel de abstracción.
Advertencia de consecuencias
A veces es útil advertir a otros programadores de sobre ciertas consecuencias. Por ejemplo, un test desactivado porque tarda demasiado tiempo en ejecutarse. Aunque con algunas herramientas de testing como junit5 se puede poner un @Ignore(«Takes too long to run») que haría innecesario el comentario.
Eso sí, esto no es un comodín para escribir código ineficiente y como he puesto el comentario de que es lento, me desentiendo.
TODOs
Que decir de los TODOs? Todos esos “esto hay que hacerlo pero no hay tiempo” desperdigados por el código esperando a que un buen día tengamos tiempo para solucionar y que se quedan olvidados hasta que alguien tiene que meter mano ahí. Volvemos a lo de siempre: es mejor eso que nada, pero es una clara señal de no estamos haciendo las cosas bien y no debería estar.
Amplificación
Se puede escribir un comentario para denotar la importancia de algo que de otra manera puede no parecerlo.
Javadocs en APIs publicas
En java (y otros lenguajes) se pueden escribir una serie de comentarios dirigidos a ser publicados en una API pública, o para que aparezcan como texto informativo de ayuda en tus clases y métodos. Toda ayuda es bienvenida, pero hay que tener en cuenta todos los consejos anteriores.
Malos comentarios
La mayoría caen en esta categoría, generalmente son excusas para un mal código y son los que más se dan.
Murmullos
Es el comentario que se escribe porque crees que deberías hacerlo, o porque el proceso lo requiere. Si lo haces asegúrate de que es el mejor comentario que puedes escribir. Un ejemplo real de un comentario que podría haber sido útil, pero que por las prisas o por no prestar mucha atención se convirtió en un enigma:
Aparentemente, si capturamos una IOException significa que no hay archivo de propiedades y esto causa que se carguen las predeterminadas. ¿Pero quien las carga? ¿Se cargan antes de la llamada a loadProperties.load? ¿O ese loadProperties.load captura la excepción, carga las predeterminadas y luego pasa la excepción para que la ignoremos? ¿O loadProperties.load carga las predeterminadas antes de intentar cargas el archivo? ¿Estaba el autor tratando de consolarse por dejar un catch vacío? O, y esta es la posibilidad más aterradora, ¿el autor estaba tratando de decirse a si mismo que tenía que volver aquí más tarde y escribir el código que cargue las predeterminadas?
¿Tu sabrías responder sin dudar? Porque yo no, y si me encontrara eso en un código que provoca un bug me acordaría de toda la familia del programador que lo escribió 🙂
Comentarios redundantes
Simplemente explican (con suerte) lo que hace un código que no necesita explicación y probablemente cueste más tiempo leerlos que entender que hace el código. No aportan información, ni son más fáciles de leer, no sirven como documentación, ni… vamos, que no sirven para nada. Y no solo eso, después de leer el 3º comentario así el resto los lees con desgana. Total, si van a ser igual de útiles…
Comentarios engañosos (mis preferidos)
Con la mejor de las intenciones (espero) se escribe un comentario que no es del todo conciso, que a nosotros si nos lo parece, pero que a un lector externo le plantea dudas. O simplemente un comentario que se ha quedado desactualizado y nadie ha tocado «por si acaso». Cuanto daño han hecho los «por si acaso».
Comentarios obligatorios
Creo que nada puede ser más nefasto que escribir un comentario solo porque estas obligado a hacerlo.
Comentarios de la jornada
Hay quien añade un comentario al principio del modulo cada vez que lo edita (esto lo he visto mucho en ABAP), que se acaban convirtiendo en una especie de log de cambios. Podían tener sentido en su momento, pero hoy en día con los sistemas de control de versiones que hay, son totalmente innecesarios.
Comentarios ruidosos
Hay comentarios que solo molestan, resaltan lo obvio y no aportan nada.
¿Has visto el error? Si ni se presta atención cuando se escribe (o copia) el comentario, ¿por que se espera que se sacará beneficio de leerlo?
No uses un comentario cuando puedes usar una función o variable
Sinceramente, ¿cual de los 2 es más claro?
Marcadores de posición
A algunos programadores les gusta marcar un determinado punto en el código, con algo así:
Puede tener sentido usarlos para llamar la atención de un punto en concreto, porque no te los esperas. Pero si se repiten, dejan de ser inesperados y simplemente los obvias, por lo que pierden su función.
Lo he visto mucho en ABAP, especialmente en el archivo de variables globales. Un consejo: si necesitas separar un archivo en bloques con algo así significa que el archivo es demasiado grande, mejor divídelo en varios.
Comentarios de cierre de llave
Hay programadores que escriben un comentario en el cierre de llaves para indicar a que bloque pertenecen:
Si necesitas hacer esto para aclararte, es una señal muy clara de que deberías escribir funciones más cortas.
Firmas
/* Added by Rick */
¡Usa un control de versiones! Git puede ser tu amigo, de verdad.
¿Quien no ha visto un comentario así de alguien que ya no está en la empresa? ¿De que sirve ahora?
¿Hay algo más odioso que esto? Vale que todos comentamos código a veces para no tener que rehacerlo si hay que volver atrás (aunque con un commit a tiempo se puede evitar usando checkout). Pero ¿por qué dejarlo si lo has probado bien y funciona? ¿No será que no lo has probado bien y lo dejas «por si acaso»?
Comentarios HTML
Esto ya es una abominación, poner estilos en los comentarios debería estar penado con salir el último de la oficina un viernes.
Información no local
Añadir información de un sistema externo (como un puerto de conexión) no solo no aporta nada, no tenemos ningún tipo de control sobre esa información.
Demasiada información
¿Para que tanto texto? ¿y con que sentido? No pongas discusiones históricas ni datos irrelevantes en tus comentarios, puede parecer útil, pero solo te aporta algo a ti.
Conexiones no obvias
La conexión entre un código y su comentario debe ser obvio, sin hacer alusiones a otros temas o detalles técnicos no relevantes.
¿Que es un filter byte? ¿Tiene relación con el +1? ¿Con el *3? ¿Con ambos? ¿Un pixel es un byte? ¿Por qué 200?
Cabeceras de funciones
Las funciones cortas no necesitan descripción y un nombre bien elegido para un función pequeña que hacer una única cosa suele ser mejor que un comentario de cabecera.
Javadocs en código no público
Los javadocs aportan valor en APIs públicas, fuera de ahí no tienen mucho sentido.
El capítulo termina con un largo ejemplo de malos comentarios y como eliminarlos.
Y con esto concluye este largo artículo sobre comentarios que se puede resumir en la cita con la que comenzaba el capítulo: no comentes mal código, reescríbelo. Espero que os haya sido útil y os haga replantearos si escribir ese comentario o mejor refactorizar.
0 comentarios