Urielmania

“El Mundo de Uriel… Pero la voz de todos”

Como mejorar tus comentarios de código fuente

Si bien el código y sus comentarios forman un conjunto, la verdad es que la mayoria de programadores apenas y le ponemos atencion al codigo fuente, como para preocuparnos de los comentarios del mismo, aunque si queremos tener un codigo elegante , limpio y facil de entender lo cierto es que tenemos que debemos prestar la debida atención a ambos apartados.

Así pues gracias ha http://www.genbetadev.com tenemos algunos consejos que podemos utilizar para mejorar los comentarios de código fuente :

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.

¿Qué conseguimos con esto? Pues además de un código fuente mucho más legible, conseguimos reducir el número de comentarios necesarios. 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.

 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.

 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.

 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.

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.

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.

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.

Acerca del Autor