Sin Comentarios

Estándar

no-comments-min

Aun me acuerdo un día de clases en la universidad (cerca de las 7:30 am), cuando el profesor luego de explicar el proceso de construcción donde el código fuente pasaba por varias fases como la compilación, ensamblado, enlazado, etc., hizo un comentario acerca del tamaño del código fuente: “Si es un código fuente de un buen programador, tendrá muchos comentarios”. En aquél momento tomé aquella frase como verdad, “Un buen código debe estar repleto de comentarios” o “Sólo eres un buen programador si comentas todo tu código”, pero sólo despues de varios años me di cuenta que eso no es nada más que una falacia.

Una de las cosas más molestas es un comentario que no aporte absolutamente nada y que, por el contrario, sólo sean un desperdicio de segundos (o incluso minutos) leyendo un trozo de texto que unicamente inspiró un insulto mental a aquél que lo creó.

Un escenario peor que el anterior no es un comentario que sólo sea molesto, sino aquél que resulta dañino. ¿Un comentario dañino?, ¿Cómo es eso posible? Pues nada más dañino para el mantenimiento de un código que un comentario cuya función actual sea la desinformación: Basas el diseño de tu código en falsos supuestos por confiar en un comentario desactualizado cuyo dueño quizás ha muerto.

Cuando nos ponemos a reflexionar en el esfuerzo que haces por ignorar estos comentarios, nos damos cuenta lo necesario de “Impartir la Palabra” de la necesidad de un buen código: un código limpio. Esto toma especial interés cuando pensamos en que es mayor el tiempo que destinamos a leer código que a escribirlo, por lo que es imperativo que dejemos bien limpio por donde vamos pasando, no solamente para otros programadores que puedan mantener tu código sino también para que tú mismo, en un par de años, cuando no te acuerdes de que fue lo que hiciste, puedas entender lo más fácil posible el código que hiciste.

comments_future

En mis inicios, naturalmente pensaba que todo comentario era bueno, después de todo estaba “aclarando” lo que estaba programando, ¿qué podía salir mal?. Sin embargo, A medida que fui avanzando y creando un criterio propio sobre lo que es útil y lo que no, sin importar lo que digan los demás. Cabe destacar que este criterio no vino a mi como una revelación, sino con trabajo duro: leyendo libros, blogs, discusiones, analizando por mi cuenta estas opiniones y separando lo que tenía sentido para mí y lo que no.

Este artículo viene a ser una especie de recopilación de mi experiencia como programador conjuntamente con experiencias de otras fuentes. Básicamente intento plasmar de una manera clara (espero) mi posición referente a los comentarios en el código.

 

La Necesidad de comentar

Hay veces en que sentimos la necesidad de expresarnos. Creemos que al colocar comentarios, podríamos ser mas reconocido por el simple hecho de añadir mas líneas al código fuente y por pensar que estamos “aclarando”. Nada mas lejos de la realidad. La verdad es que los comentarios sólo (de)muestran nuestra incapacidad de comunicar nuestra intención usando la única herramienta realmente necesaria para tal fin: el código.

Si te ves en la necesidad de tener que escribir un comentario para “aclarar” lo que supone que debe hacer tu código, has fracasado como programador al demostrar tu capacidad de crear un código limpio, elegante, simple, y entendible para otras personas además de ti. Si has llegado a este punto, bien podrías hacerle un favor al mundo al no seguir consumiendo su preciado oxígeno….(Bazzinga!…?).

Cualquier tonto puede escribir código que entienda una computadora. Los buenos programadores escriben código que entienda un humano.
Martin Fowler

La responsabilidad de explicar qué hace el código debe venir del código mismo, no de los comentarios. Los comentarios no son confiables, ya que el código suele actualizarse en el tiempo, mientras que los comentario pueden perdurar sin que nadie les de el mantenimiento adecuado. Así que en lugar de andar pensando en en comentar tu código asqueroso, piensa en limpiarlo de una vez por todas 🙂

Toma el siguiente código como ejemplo sencillo y analiza cuál de ellos es más fácil de entender.

// Chequear si el empleado es elegible para los beneficios completos
if ((empleado.flags & HORA_FLAG) && (empleado.edad > 65)) 

O este.

if (empleado.esElegibleParaBeneficios())

 

Malos comentarios

Malos comentarios no son los que otras personas dicen de tu código, sino los que ellos dicen por sí mismos. A continuación vamos a ver algunos tipos de comentarios que debes evitar a toda costa.

Comentarios Ruidosos

Esos comentario que solo hacen perder tu tiempo. No añaden ningún tipo de valor y la verdad solo causan molestia al tener que ignorarlos. Lo interesante es que esto lo puedes encontrar en muchas librerías y componentes open source.

 //The processor delay for this component.
 protected int backgroundProcessorDelay = -1;

//The container event listeners for this Container.
 protected ArrayList listeners = new ArrayList();

//Default constructor.
 protected AnnualDateRule() {}

 

Comentarios Redundantes

¿Quien no ha visto un comentario escrito por el mismísimo “Captain Obvious”?.

/** The day of the month. */
private int dayOfMonth;
/**

* Returns the day of the month.
*
* @return the day of the month.
*/

public int getDayOfMonth() {
return dayOfMonth;
}

 

Comentarios Obligatorios

Trabajando para un proyecto, el equipo tenía la regla de que todo código debía estar documentado en Javadoc. Un regla totalmente absurda para código interno. Jamás vi en ese proyecto un comentario que realmente diera valor a su uso. Más aun, “forzaban” a los desarrolladores a cumplir esta regla a través de analizadores estáticos de código como Checkstyle. Lo único que lograban era que los desarrolladores (yo incluido) usaran plugins para Eclipse del estilo JAutodoc para burlar a Checkstyle y generar Javadoc que no era biodegradable. Este se mantenía por meses mintiéndote acerca de la función, ya que muchas veces la función se había modificado tanto, que el comentario no reflejaba adecuadamente su función. El resultado al final era algo como esto:

/** The name. */
private String name;

/** The version. */
private String version;

/** The version. */
private String info;

/**
 * 
 * @param title The title of the CD
 * @param author The author of the CD
 * @param tracks The number of tracks on the CD
 * @param durationInMinutes The duration of the CD in minutes
 */
 public void addCD(String title, String author, int tracks, int durationInMinutes) {
   CD cd = new CD();
 }

¿El resultado?. Una falsa sensación de soporte motivado por un deseo de documentar “todo”.

Comentarios Bitácora

Clásico escenario donde se lleva una bitácora se los cambios realizados y quién los realizó. Totalmente inútiles en estos días donde a través de sistemas de control de versiones modernos podemos señalar al culpable de un fallo y llevarlo hasta el suicidio. Estos sistemas como GIT o SVN llevan registros de la fecha, autor, cambios, etc., que muy fácilmente pueden ser consultados. No hay necesidad de hacer esto:

// 13-Mar-2010 : Se implementó una interfaz (Gabriel Espinel);
// 29-May-2011: Arreglado un error (Juanito Perez);
// 05-Jan-2014 : Arreglado un error en función foo() (1096282) (Mateneme porfavor);

De igual manera aplica para comentarios para atribuirse el código:

/** Creado por Gabriel 
* @since ALGUNA_FECHA
*/

Código comentado

Al mejor estilo de una mala película de terror donde entierran un cadáver bajo tierra, pero al final siempre termina regresando para joder. Lo mismo sucede cuando comentas el código para no borrarlo “por si acaso”. Este código tiende a tener un efecto en otros desarrolladores que sienten que no deben borrar ese código comentado porque “alguna buena razón debe haber” para que esté ahí, persistiendo esa basura a lo largo del tiempo. Este caso es bastante frecuente, en especial en proyectos con bastantes personas y con bastante movilidad de personal.

InputStreamResponse response = new InputStreamResponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
// InputStream resultsStream = formatter.getResultStream();
// StreamReader reader = new StreamReader(resultsStream);
// response.setContent(reader.read(formatter.getByteCount()));

Javadocs para códgo privado

Generar JAvadoc para código que no será consumido como parte de alguna API pública, solamente genera distracciones y trabajo extra al equipo encargado del mantenimiento.

 

Buenos comentarios

Particularmente no los considero exactamente “buenos”. Me parece que es una palabra que fomenta el uso de los comentarios. Quizás “aceptable” sea un mejor adjetivo.

La verdad es que hay veces en que por una razón u otra nos vemos en la necesidad de colocar un comentario para notificar algo a alguien (quien, como mencioné anteriormente, puede que ese alguien puede ser otro persona o puedes ser tu mismo en el futuro, odiando al “tu” de hoy por tan inútil texto). Así que siempre tenlo en cuenta al hacer un comentario.

Comentario informativo

El siguiente código se puede considerar útil al ahorrar tiempo de entendimiento del código. Claramente el código se hace un poco confuso, mientras que el comentario tiene bien definida su función.

// Formato kk:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");

Sin embargo, hay que tener mucho cuidado. Ese comentario podría perder validez en el tiempo si el patrón llega a cambiar y no se actualiza. Requiere de disciplina por parte de los miembros del equipo evitar que esto suceda.

Explicación de la intención

Hay veces en que simplemente debemos dar una explicación detrás de una decisión de diseño. En estas situaciones, es necesario que el comentario se enfoque en el Por Qué del código y no en el Qué. Si debes explicar qué hace tu codigo, arreglalo, no lo comentes.

Una vez conversando con un buen compañero mío y un excelente programador, caímos en este tema. Su posición era que esta regla no aplicaba, si quieres explicar el por qué de un decisión entonces hazlo en la documentación del sistema y asi dejarás libre el código de ese comentario. Sin embargo, mi opinión es que ese cambio de contexto entre el código y un documento (que puede ser muy largo) resulta una carga cognitiva innecesaria. Leer un código, no entenderlo, tener que buscar un documento de texto y empezar a buscar el por qué me parece un poco extremo. El por qué podría resumirse en un par de líneas (máximo) y de ser necesario hacer una referencia al documento.

Advertencia de fin de mundo

Comentarios útiles para advertir a los demás sobre algún efecto o consecuencias. Por ejemplo, porqué una prueba esta deshabilitada.

// No ejecutar a menos que tengas tiempo libre
public void __testEsperar() {
writeLinesToFile(10000000);
}

 

Énfasis

Se puede usar un comentario para amplificar la importancia de algo que de otra manera podría pasar desapercibido.

public void controlador(@Param String param) {
//Truco para solucionar bug 12345 del framework XXX referente a pase de parametro
//Ver http://bug.framework.com/XXX
springParam = springParam.replace("-", " ")
}

 

Tareas Pendientes

Uno de los que, a mi parecer, son bastante útiles son los comentarios “TODO”. Estos comentarios son resaltados por los IDE modernos, permitiendo hacer seguimiento de que queda por hacer en el código.

try {
  //hacer algo aqui
} catch (Exception e) {
  log.error(e)
  //TODO: enviar una notificación al administrador
}

 

Nota: estos comentarios terminan siendo como una tarjeta de crédito. No quieres tener todo tu proyecto repleto de estos, ya que se empieza a acumular la deuda técnica. Hay que usarlos con cuidado.

Javadocs en API públicas

Si estas escribiendo una API de uso público, entonces una buena documentación es casi obligatorio. En este escenario es un muy buen uso de los comentarios para generar una documentación útil y descriptiva del API. Sin embargo, considera que igualmente es vulnerable a todos los problemas como eventualmente no estar sincronizado con el código, mintiendo al que la use. Mucha disciplina con estos comentarios.

Conclusiones

Vimos que el león no es como lo pintan, hay que tener mucho cuidado con el uso de comentarios. Es necesario empezar a desarrollar habilidades para generar un código limpio, para que puedan expresarse de una mejor manera usando el código en lugar de usar los comentarios para tal fin.

Si te gustó, ¡comparte!Share on FacebookShare on Google+Tweet about this on TwitterShare on LinkedInShare on Reddit
  • Christian Carmona

    jajajajaja esta buenisimo este post! gran parte de las empresas pide comentarios obligatorios, te obligan a comentar cosas donde el comentario realmente esta de más.