Web BizarroWeb Bizarro

Suscríbete a nuestro Newsletter

X

Únete a nuestra lista de correos para recibir semanalmente actualizaciones de nuestro contenido.

Cómo mejorar los comentarios de tu código fuente

Cómo mejorar los comentarios de tu código fuente 21.MAY.14

Gianfranco Lemmo
Fundador WebBizarro

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.

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)

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.

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.

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.

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.