04.07.08

Buenas Prácticas: La Importancia de los Comentarios

Posted in .NET, Buenas Prácticas, Gestión del Mantenimiento, Java, Programación at 8:00 am by Miguel

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.

Permalink