2008-02-05 23:23:26

Es copia de: http://www.variablenotfound.com/2007/12/13-consejos-para-comentar-tu-cdigo.html

13 Consejos para comentar tu c�digo

Hace unos d�as publicaba una entrada donde hablaba de los problemas que generan la inclusi�n y el mantenimiento de comentarios en el c�digo fuente de nuestras aplicaciones, aunque para no extenderme mucho s�lo cit� brevemente algunos aspectos a tener en cuenta a la hora de afrontar estos inconvenientes.

Ahora, partiendo de estos consejos, la abundante literatura que hay sobre el tema y mi propia experiencia, he creado los 13 consejos para comentar tu c�digo, que contribuir�n a hacerlo m�s inteligible y por tanto a incrementar su mantenibilidad a lo largo del tiempo.

1. Comenta a varios niveles
Comenta los distintos bloques de los que se compone tu c�digo, aplicando un criterio uniforme y distinto para cada nivel. Puedes, por ejemplo, seguir un modelo como:

- En cada clase, incluir una breve descripci�n, su autor y fecha de �ltima modificaci�n
- Por cada m�todo, una descripci�n de su objeto y funcionalidades, as� como de los par�metros y resultados obtenidos

En realidad, lo importante es ce�irse a unas normas (com�nmente aceptadas si se trata de trabajo en equipo) y aplicarlas siempre. Las reglas concretas pueden ser elegidas a la conveniencia de cada cual.

Obviamente, una soluci�n bastante aceptable e incluso aconsejable es utilizar las convenciones y herramientas (como XML en C# � Javadoc para el mundo Java) que ayudan y facilitan esta tarea.
2. Usa p�rrafos comentados
Como complemento al punto anterior, es recomendable dividir un bloque de c�digo extenso en «p�rrafos» que realicen una tarea simple, e introducir un comentario al principio de forma que se gu�e al lector, precedi�ndolos, adem�s, de una l�nea en blanco que ayude a separar cada uno del anterior.

...

// Comprobamos si todos los datos
// son correctos
foreach (Record record in records)
{

if (rec.checkStatus()==Status.OK?)
{

...

}

// Ahora pasamos a realizar las
// transacciones
Context ctx = new Application Context?();
ctx.BeginTransaction();
...

3. Tabula por igual los comentarios de l�neas consecutivas
Si tenemos un bloque de l�neas de c�digo donde existe por cada una de ellas un comentario, es buena costumbre tabularlos todos a la misma posici�n, de forma que quedar�n alineados y ser�n m�s sencillos de leer, sobre todo si forman parte de la misma frase.

const MAX_ITEMS = 10; // N�mero m�ximo de paquetes
const MASK = 0x1F; // M�scara de bits TCP

Ojo a las tabulaciones. Hay editores que usan el car�cter ASCII (9) y otros, en cambio, lo sustituyen por un n�mero determinado de espacios, que suelen variar seg�n las preferencias personales del desarrollador. Lo mejor es usar espacios simples o asegurarse de que esto es lo que hace el IDE correspondiente.
4. No insultes la inteligencia del lector
Debemos evitar comentarios absurdos como:

if (a == 5) // Si a vale cinco, ...

counter = 0; // ... ponemos el contador a cero

...

Este exceso necesita mucho tiempo a la hora de su creaci�n, lo necesitar� para su mantenimiento y, adem�s, la mayor�a de las veces distraer� al lector con detalles que no es necesario conocer o que pueden ser deducidos echando un vistazo al c�digo.
5. S� correcto
Evita comentarios del tipo «ahora compruebo que el est�pido usuario no haya introducido un n�mero negativo», o «este parche corrije el efecto colateral producido por la pat�tica implementaci�n del inepto desarrollador inicial».

El uso de este tipo de comentarios no dice nada a favor de su creador, y, adem�s, nunca se sabe qui�n los va a leer en el futuro. Emarts, en «Sapos, culebras y c�digo fuente» muestra ejemplos de comentarios de este tipo.

Otro tema relacionado y, a mi entender, igualmente importante: cuida la ortograf�a. El hecho de que los comentarios no se vean desde el exterior no implican que puedas descuidarlos. Una ortograf�a correcta mejora la calidad de la expresi�n escrita y, por tanto, de la comunicaci�n, que es de lo que se trata.
6. No pierdas el tiempo
No comentes si no es necesario, no escribas nada m�s que lo que necesites para transmitir la idea. Nada de dise�os realizados a base de caracteres ASCII, ni florituras, ni chistes, ni poes�as, ni chascarrillos.

En resumen, mant�n los comentarios simples y directos, pues de lo contrario har�s perder tiempo a tu sucesor. Para entender el efecto negativo de una verborrea excesiva, no hay como echar un vistazo a Hyperverbosity, publicado en Worse Than Failure hace unos d�as.
7. Utiliza un estilo consistente
Hay quien opina que los comentarios deber�an ser escritos para que los entendieran no programadores. Otros, en cambio, piensan que debe servir de ayuda para desarrolladores exclusivamente.

En cualquier caso, coincidiendo con Ryan Campbell en su post Successful Strategies for Commenting Code, lo que importa es que siempre sea de la misma forma, orientados al mismo destinatario. Personalmente, dudo mucho que alguien de un perfil alejado a la programaci�n vaya a acercarse al c�digo, por lo que, para mi gusto, bastar�a con cubrir el segundo caso de los expuestos anteriormente.
8. Para los comentarios internos usa marcas especiales

Y sobre todo, aunque no �nicamente, cuando se trabaja en un equipo de programaci�n en el que varias personas pueden estar tocando las mismas porciones de c�digo. El ejemplo t�pico es el comentario TODO (to-do, por hacer), que describe funciones pendientes de implementar:

int calcula(int x, int y)
{

// TODO: implementar los c�lculos
return 0;

}

En este caso los comentarios no se usan para explicar una porci�n de c�digo, sino para realizar anotaciones sobre el mismo a las que hay que prestar especial atenci�n. Eso s�, si usas esta t�cnica, recuerda que debes actualizarlos conforme las anotaciones dejen de tener sentido.
9. Comenta mientras programas
Ve introduciendo los comentarios conforme vas codificando. No lo dejes para el final, puesto que entonces te costar� m�s de el doble de tiempo, si es que llegas a hacerlo. Olvida las posturas “no tengo tiempo de comentar, voy muy apurado”, “el proyecto va muy retrasado”... son simplemente excusas. Si tu intenci�n es comentar el c�digo, no te enga�es y �hazlo!

Hay incluso quien opina que los comentarios que describen un bloque deber�an escribirse antes de codificarlo, de forma que, en primer lugar, sirvan como referencia para saber qu� es lo que hay que hacer y, segundo, que una vez codificado �stos queden como comentarios para la posteridad. Un ejemplo:

public void Procesa Pedido?()
{

// Comprobar que hay material
// Comprobar que el cliente es v�lido
// Enviar la orden a almac�n
// Generar factura

}

La codificaci�n de cada una de las tareas descritas en el lenguaje correspondiente se realizar�a justo debajo del comentario, quedando �ste como encabezado de p�rrafo (como se describe en el consejo 2).
10. Comenta como si fuera para t� mismo. De hecho, lo es.
A la hora de comentar no pienses s�lo en mantenimiento posterior, ni creas que es un regalo que dejas para la posteridad del que s�lo obtendr� beneficios el desarrollador que en el futuro sea designado para corregir o mantener tu c�digo.

En palabras del genial Phil Haack,

«tan pronto como una l�nea de c�digo sale de la pantalla y volvemos a ella, estamos en modo mantenimiento de la misma»

Como consecuencia, nosotros mismos seremos los primeros beneficiaros (o v�ctimas) de nuestro buen (o mal) hacer.
11. Actualiza los comentarios a la vez que el c�digo
De nada sirve comentar correctamente una porci�n de c�digo si en cuanto �ste es modificado no se actualizan tambi�n los comentarios. Ambos deben evolucionar paralelamente, pues de lo contrario estaremos haciendo m�s dif�cil la vida del desarrollador que tenga que mantener el software, al facilitarle pistas incorrectas para comprenderlo.

Atenci�n especial a las refactorizaciones autom�ticas, que suelen introducir cambios en distintos puntos del c�digo de un proyecto, dejando los comentarios obsoletos en ese mismo instante.
12. La regla de oro del c�digo legible
He dejado para el final uno de los principios b�sicos para muchos desarrolladores: deja que tu c�digo hable por s� mismo. Aunque se sospecha que este movimiento est� liderado por programadores a los que no les gusta comentar su c�digo ;-), es totalmente cierto que una codificaci�n limpia puede hacer innecesaria la introducci�n de textos explicativos adicionales.

Recordemos, por ejemplo, el c�digo introducido en el post «Interfaces fluidos (fluent interfaces)", donde se muestra lo que esta t�cnica puede aportar a la claridad y autoexplicaci�n en un desarrollo:

Console.Write Line?(«Resultado: " +

new Calculator()

.Set(0)
. Add(10)
. Multiply(2)
. Substract(4)
. Get()

);

A la vista del ejemplo, �es necesario a�adir alg�n comentario para que se entienda qu� hace el c�digo? El uso de nombres apropiados (aconsejo leer el cl�sico Ottinger's Rules), indentaci�n correcta y la adopci�n de gu�as de estilo (pod�is ver algunas en la wikipedia, o googleando un poco) facilitan enormemente la escritura homog�nea e inteligibilidad directa del c�digo.

El no cumplimiento de esta regla hace que a veces los comentarios puedan parecer una forma de pedir perd�n al desarrollador que se encargar� del mantenimiento del software.

13. Difunde estas pr�cticas entre tus colegas
Obviamente, aunque ya hemos comentado en el punto 10 que nosostros mismos nos beneficiamos inmediatamente de las bondades de nuestro c�digo comentado, la generalizaci�n y racionalizaci�n de los comentarios y la creaci�n c�digo inteligible nos favorecer� a todos, y sobre todo en contextos de trabajo en equipo. No dudes, por tanto, en crear cultura de comentarios en tu entorno.

WikiJuanan - TreceConsejosParaComentarTuC�digo

2008-02-05 23:23:26

13 Consejos para comentar tu c�digo