Problemas al comentar el código fuente

Si existieran los diez mandamientos del programador, seguro que uno de ellos sería "comenta tu código". Y es que está claro que la mantenibilidad de una aplicación o módulo es posible siempre que los profesionales encargados de ella sean capaces de entender perfectamente qué hace el software y cómo lo hace, y es aquí donde un código correctamente documentado puede facilitar enormemente la tarea.

Todos los lenguajes de programación facilitan la inclusión de texto libre, no estructurado, con objeto de que el programador explique a futuros mantenedores del software los principales aspectos del código fuente que está observando, el por qué de determinadas decisiones, o, en definitiva, aclarar lo que considere oportuno. Sin embargo, esta libertad y falta de normalización acarrea una serie de inconvenientes que deben ser tenidos en cuenta, y que comentó Chad Myer hace unas semanas.

En primer lugar, es importante ser conscientes de que estos textos están fuertemente ligados al código que comentan y, obviamente, al no ser comprobados por ningún sistema automático (como un compilador), es fácil que contengan errores:


// Retorna la suma de a y b
public int multiplica(int a, int b)
{
...

Tampoco puede asegurarse que los comentarios sean útiles; de hecho, parte de los comentarios que leemos son obviables y totalmente innecesarios, auténticos insultos a la inteligencia, del tipo:


if (a > 5) // Si a es mayor que cinco, ...
counter = 0; // ... ponemos el contador a cero
...

 La inclusión de este tipo de comentarios no harían sino añadir "ruido" a un código perfectamente inteligible de forma directa.

Y hablando de comentarios prescindibles, es curioso ver su utilización como vía de escape y desfogue de algunos programadores, que no dudan en añadir todo tipo de artillería a sus creaciones, como las mostradas en el Contador de palabrotas del Kernel de Linux, arremetiendo contra los usuarios, colegas o todo aquél que pase por delante en el momento apropiado.

Otro hecho bastante frecuente es que los comentarios sean introducidos al crear un código pero que no sean actualizados de forma paralela a éste, lo que da lugar a textos obsoletos y sin sentido en su contexto. Y no hablo sólo de actualizaciones tiempo después de su creación, también las realizadas minutos u horas después de la programación inicial como consecuencia de optimizaciones y refactorizaciones, incluso realizadas por el mismo desarrollador.


// Si x es true, retorna a+b
// Si no, retorna a-b
public int calcula(int a, int b)
{
...

A pesar de todos estos problemas, normalmente generados por falta de rigor durante su creación y actualización, los comentarios son absolutamente necesarios para el futuro mantenimiento de un sistema y deben tratarse como parte fundamental en una pieza de código y prestarle la misma atención que a éste. Recordemos la famosa frase de Martin Fowler:

"Cualquier tonto puede escribir código que entienden las computadoras. Los buenos programadores escriben código que entienden las personas."


Para ello, como dice Bernhard Spuida en su magnífico documento The Fine Art of Commenting, hay que luchar contra actitudes negativas como:

  • el orgullo del programador ("no me hacen falta comentarios para entender lo que hace cualquier código", "yo escribo código que entiende cualquiera"). No te engañes, un código medianamente complejo te llevará tiempo entenderlo en cuanto hayan pasado unos meses incluso a tí mismo, así que imagina a otro desarrollador.
  • la pereza y procrastinación ("ya comentaré el código más adelante"). No te engañes, no lo harás; además, se estima que el tiempo necesario para añadir comentarios útiles a un código se duplica (como mínimo) si no se realiza en el momento de la codificación.
  • la excusa del deadline ("el proyecto va demasiado apurado como para ponerme a comentar el código"). No te engañes, los minutos de tardarás en comentar apenas afectarán a los plazos, y sí añadirán mantenibilidad al sistema.

Y es que, citando a Ryan Campbell en su post Successful Strategies for Commenting Code,

"comentar el código es como limpiar el cuarto de baño; nadie quiere hacerlo, pero el resultado es siempre una experiencia más agradable para uno mismo y sus invitados"


Publicado en: Variable Not Found.

Published 25/11/2007 20:35 por José M. Aguilar
Comparte este post:
http://geeks.ms/blogs/jmaguilar/archive/2007/11/25/problemas-al-comentar-c-243-digo-fuente.aspx

Comentarios

# re: Problemas al comentar el código fuente

Una reflexión muy interesante, si señor

y muy bien escrito y documentado :-)

Un saludo

JM

Monday, November 26, 2007 8:54 AM por José M. Alarcón Aguín

# re: Problemas al comentar el código fuente

Hola, el problema es que muchas veces, uno nunca "tiene tiempo", ni ganas de buscar eliminar aquellas dependecias "codigo/persona"

tambien se pasa por un problema de conocimiento, orden, cultura...

un saludo.

Monday, November 26, 2007 10:31 PM por Jersson

# re: Problemas al comentar el código fuente

Me ha parecido un texto muy reflexionado. Al menos me he sentido identificado en muchas de las situaciones que se exponen en el texto.

Creo que es muy conveniente tener una guia de estilo a la hora de comentar codigo. Muy importante sobre todo comentar los encabezados de los metodos y propiedades. Parametros, valores de retorno y breve descripción del proposito.

Los comentarios en el codigo son un buen complemento a la documentación. Claro, cuando esta existe y es de calidad.

Un saludo

Fidel Ortega

Monday, November 26, 2007 11:11 PM por Fidel Ortega

# re: Problemas al comentar el código fuente

Me ha parecido un excelente articulo, principalmente por la claridad de la explicacion.

Gracias,

Un saludo.

Sendagorta

Monday, November 26, 2007 11:41 PM por Sendagorta

# re: Problemas al comentar el código fuente

Muy bueno, me identifico plenamente. Quizás yo hubiera añadido esa buena práctica de definir de forma autoexplicativa los nombres de las funciones y variables. Te ahorras comentar mucho y el código queda muy legible a los humanos.

Tuesday, November 27, 2007 12:45 AM por Ondias

# (para programadores) Pequeña guía a seguir a la hora de programar, en lo que a comentar el código se refiere

Es una pequeña guia, que en la práctica es la que debe tener bien clara y predefinida en su cabeza todo programador a la hora de picar teclas y comentar lo que hace. :)

Tuesday, November 27, 2007 9:57 AM por meneame.net