Introducción a C#
Por Nacho Cabanes, versión 0.93 de 16-abr-2010


(Nota: Estás viendo una versión del curso antigua, creada en 2009. Es recomendable que sigas la versión 2015, mucho más actualizada, con contenidos más detallados, más ejemplos y más ejercicios propuestos)

11.4. Documentación básica de programas

La mayor parte de la documentación de un programa "serio" se debe realizar antes de comenzar a teclear:

Casi todos esos diagramas caen fuera del alcance de este texto: en una introducción a la programación se realizan programas de pequeño tamaño, para los que no es necesaria una gran planificación.

Aun así, hay un tipo de documentación que sí debe estar presente en cualquier problema: los comentarios que aclaren todo aquello que no sea obvio.

Por eso, este apartado se va a centrar en algunas de las pautas que los expertos suelen recomendar para los comentarios en los programas, y también veremos como a partir de estos comentarios se puede generar documentación adicional de forma casi automática.

11.4.1. Consejos para comentar el código

Existen buenas recopilaciones de consejos en Internet. Yo voy a incluir (algo resumida) una de José M. Aguilar, recopilada en su blog "Variable not found". El artículo original se puede encontrar en:

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

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, por ejemplo:

(Lo importante es ceñirse a unas normas y aplicarlas siempre).

2. Usa párrafos comentados

Además, es recomendable dividir un bloque de código extenso en "párrafos" que realicen una tarea simple, e introducir un comentario al principio además de una línea en blanco para separar bloques:

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

3. Tabula por igual los comentarios de líneas consecutivas

Si tenemos un bloque de líneas de código, cada una con un comentario, será más legible si están alineados:

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

Ojo a las tabulaciones. Hay editores de texto que usan el carácter ASCII (9) y otros, 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, ...
      contador = 0; // ... ponemos el contador a cero
   ...

5. Sé correcto

Evita comentarios del tipo "ahora compruebo que el estúpido usuario no haya introducido un número negativo", o "este parche corrige el efecto colateral producido por la patética implementación del inepto desarrollador inicial".

Relacionado e igualmente importante: cuida la ortografía.

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.

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, lo que importa es que siempre sea de la misma forma, orientados al mismo destinatario.

8. Para los comentarios internos usa marcas especiales

Y sobre todo cuando se trabaja en un equipo de programación. 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;
  }

9. Comenta mientras programas

Ve introduciendo los comentarios conforme vas codificando. No lo dejes para el final, puesto que entonces te costará más del 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.

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 ProcesaPedido()
   {
      // Comprobar que hay material
      // Comprobar que el cliente es válido
      // Enviar la orden a almacén
      // Generar factura
   }

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"

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, o estaremos haciendo más difícil la vida del desarrollador que tenga que mantener el software, al darle pistas incorrectas.

12. La regla de oro del código legible

Es 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:

  Console.WriteLine("Resultado: " +
    new Calculator()
          .Set(0)
          .Add(10)
          .Multiply(2)
          .Substract(4)
          .Get()
  );

13. Difunde estas prácticas entre tus colegas

Aunque 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, sobre todo en contextos de trabajo en equipo.