Diez consejos para mejorar tus comentarios de código fuente

El otro día me encontré en Twitter esta fantástica viñeta de Sinergia sin control, a propósito de los comentarios en el código fuente. En ella se ponen de manifiesto los problemas típicos que solemos encontrar en ellos.

No hay que olvidar que el código y sus comentarios forman un conjunto. Así que debemos prestar la debida atención a ambos apartados. Para que nuestro código sea elegante, limpio y fácil de mantener, podemos seguir los siguientes consejos.

1. Utiliza nombres descriptivos

Es una regla básica, que aunque no está directamente relacionada con los comentarios, influye mucho en ellos. Nuestras variables, clases y métodos, deben tener un nombre descriptivo.

Lo normal es que los nombres de las clases sean sustantivos que representen una entidad (Cliente, Proveedor etc.). Los métodos representan una acción, por lo que su nombre suele contener algún verbo (devolverNuevoCliente, calcularPrecioTotal etc.). Además deberemos intentar que las variables, propiedades y parámetros, tengan un nombre que describa el valor que contienen (total_clientes, total_presupuesto etc.).

¿Qué conseguimos con esto? Pues además de un código fuente mucho más legible, conseguimos reducir el número de comentarios necesarios. Por ejemplo:

var cliente = servicioClientes.recuperarDatosCliente(id_cliente);
if (cliente.estaActivo)
{
   cliente.UlitmoAcceso=Date.Now;
   servicioDatos.guardaCliente(cliente);
}

Al usar nombres descriptivos el código no necesita comentarios adicionales. Cualquier programador que revise el código, será capaz de hacerse una idea de lo que hace el código.

2. Los comentarios tienen que ser útiles

No hace falta explicar cosas obvias. El código fuente en el 98% de los casos lo va a leer otro programador. O al menos alguien con conocimientos de programación. Por ejemplo:

// Comprobamos si el contador es 5
if (contador == 5)

Ese comentario no aporta nada. Mejor si lo eliminamos. Mejor todavía si no llegamos ni a escribirlo.

3. Piensa si un comentario es necesario antes de añadirlo

Si tenemos que añadir un comentario es mejor pensarlo un poco antes de hacerlo. ¿Por qué voy añadir este comentario? ¿Es realmente necesario? ¿Puedo refactorizar mi código para evitarlo? Quizá el código que hemos escrito es demasiado complejo y por eso necesita ser explicado. En ese caso podremos separarlo en métodos más sencillos. Siempre siguiendo la norma de usar nombres descriptivos.

Con esta simple idea, también podemos identificar posibles errores de diseño

4. Evita comentarios dentro de métodos o funciones

Puede ser útil comentar lo que hace un método antes de su declaración. Incluso podemos comentar sus parámetros. Pero hay que tener en cuenta que debemos comentar el "qué" y no el "cómo". Es decir, debemos explicar qué hace nuestro método. El "cómo" hace el método su función ya va explicado en el código.

5. No comentes código eliminado

A veces nos vemos obligados a eliminar parte del código. Y a veces, en un arranque de "por si acaso", comentamos el código eliminado, para no perderlo. Esto es algo que no tiene sentido en el siglo XXI. Ya deberíamos tener un sistema de control de código fuente para estas cosas. Y si no lo tenemos, tenemos problemas más graves que los comentarios.

6. Piensa que los comentarios también hay que mantenerlos

Un comentario tiene que ser claro y explicar bien las cosas. Pero los comentarios también hay que mantenerlos. Si describimos lo que hace un método, y en algún momento la funcionalidad cambia, también tendremos que actualizar los comentarios. Por tanto mejor que los comentarios sean breves y concisos.

7. Ten cuidado con los comentarios engañosos

Es algo que no suele hacerse a propósito, pero que puede darnos más de un quebradero de cabeza. Tiene que ver con el punto anterior y el problema de no mantener los comentarios. A veces porque nos dejamos algo por hacer, o por qué una especificación ha cambiado, nuestro comentario queda obsoleto. O lo que es peor, el comentario expresa algo distinto a lo que en realidad se está haciendo. Si nos fiamos del comentario, podemos generar errores no esperados.

public int devolverEstadoCliente(){
 // TO-DO
 return 0;
}

Y luego en otra parte del código encontramos los siguiente

//Borramos el cliente si está desactivado
if (cliente.devolverEstadoCliente() == 0)
   servicioDatos.borrarCliente(cliente);

En el ejemplo el problema se ve fácil porque el código está próximo. Pero si tenemos el código repartido en distintas clases, podemos estar borrando cliente sin querer.

8. Sigue siempre un mismo estilo

Es recomendable comentar el código siempre de la misma manera. Un estilo definido ayuda a comprender el código a quién lo está leyendo. Si siempre comentamos un método con una introducción y una descripción de los parámetros, tendremos que ser constantes y hacerlo en todos los métodos. Si no la persona que lo lea puede acabar confundido por la disparidad de criterios.

9. No dejes los comentarios para el final

En general a los que desarrollamos, no nos gusta comentar. Es algo aburrido, que solemos dejar para más tarde. Pero procrastinar el comentado del código es una mala idea por varias razones. La primera es que, al final, nos veremos obligados a comentar un gran volumen de código de golpe. Eso es todavía más aburrido, y nuestros comentarios serán peores. La segunda es que las ideas pierden frescura según pasa el tiempo. Escribir comentarios de código que no acabamos de hacer es más complicado y lleva más tiempo.

Mejor comenta a la vez que programas. O mejor, comenta antes de programar. Escribiendo lo que tienes que hacer hacer, tendrás una mejor comprensión del problema.

10. Es mejor ser educado

Esto depende de un poco del ámbito del código fuente. En ámbitos laborales, deberemos ser serios y correctos. Y más si el código es para un cliente. Si el código lo estamos haciendo para nosotros, los comentarios pueden tener un tono más distendido. Eso sí, mejor evitar palabras malsonantes, porque nunca se sabe quién puede leer el comentario.

Estos son algunos consejos, pero seguro que hay más. ¿Qué reglas o técnicas soléis seguir vosotros a la hora de comentar vuestro código?

Imagen | xmodulo