Buenas Prácticas: La Importancia de los Comentarios

Poner comentarios en un código siempre se ha considerado por la mayorí­a como una labor aburrida, tediosa, poco motivante en general.
Luego está el otro extremo, los que se dedican a poner parrafadas de libro en cada lí­nea o en la descripción de los métodos.
Como siempre, los extremos no suelen ser las mejores soluciones. Lo recomendable es siempre comentar, pero a ser posible sin redactar el quijote por cada método o trozo de código. Los comentarios pueden resultar básicos para entender qué está haciendo un determinado algoritmo.
Es algo bastante natural, sobre todo para los programadores con poca experiencia, el tener la creencia de que se van a acordar de lo que hací­a el algoritmo, por lo que bajo esa premisa el uso del comentario pierde sentido para ellos. A medida que la experiencia va llegando se llegan a nuevas conclusiones:
1) Como me he encontrado código que no he hecho yo y no está comentado no tengo ni idea de lo que hace. Además, el compañero que lo ha hecho o está a tope y no me lo puede contar o justamente se ha ido una semana de vacaciones. Mira tíº por donde esto tiene que estar arreglado esta misma mañana por lo que me voy a tener que quedar comiendo delante del ordenador, así­ que, la próxima vez que programe algo que no es para mi, lo comentaré, y le diré a mi compañero que haga lo mismo.
2) Estoy solventando una incidencia y recuerdo perfectamente que el código lo hice yo, pero miro y remiro lo que hace y no me acuerdo para nada de por qué tomé esta solución. Es más, no sé ni qué hace o para que sirve esto. Será mejor que comentemos los métodos al crearlos, incluidos los parámetros que se la pasan, así­ nos evitaremos estos problemas.
3) Mira qué bien, el método está comentado, sé lo que hace por lo que voy a arreglar la incidencia en un momento. El problema viene cuando resulta que alguien cambió el comportamiento del método y no actualizó el comentario, entonces me estoy creyendo que hace lo que dice el comentario… ¿os imagináis el resultado, no? … Está bien, además de añadir un comentario al crear el método, cuando lo modifique también lo ajustaré.
Por ejemplo, trabajando con C# el añadir comentarios a método es muy cómodo, íºnicamente pulsad tres veces “/” justo en la linea de encima de la definición del método y os aparecerá la estructura xml que tenéis en el método de abajo (sin rellenar claro, la tendréis que rellenar vosotros).
/// <summary>
/// Inserta un nuevo coche
/// </summary>
/// <param name=”codigoCoche”>Identifica de forma íºnica el coche</param>
/// <param name=”nombreCoche”>nombre del coche</param>
/// <param name=”numeroPuertas”>níºmero de puertas del coche</param>
/// <param name=”codigoMarca”>identifica de forma íºnica la marca del coche</param>
public void Insert(int codigoCoche, string nombreCoche, int numeroPuertas, int codigoMarca)
{
 // código necesario para la inserción
}
La buení­sima noticia al respecto es que ahora cuando utilicéis el Intellisense de Visual Studio, al seleccionar el método os aparecerán los comentarios que habéis puesto, algo que aumentará vuestra productividad.
Para llevar a cabo la misma acción con VB.NET en lugar de usar “/” tenéis que usar “‘” (comilla simple).
Otra buení­sima noticia es que existen herramientas que a partir de los comentarios que añadais a vuestros métodos, clases, interfaces, propiedades generan documentación automáticamente. Los famosos JavaDoc en java son un ejemplo, los archivos .chm para .NET lo mismo.
Saludos.
Miguel.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.