Honestamente, el título confunde: Este artículo comenta mucho los comentarios.

Programadores están obligados a hacer su código funcionar. Una restricción que les quita mucha creatividad. Sólo una minoría privilegiada, que escribe comentarios en el código, tiene la posibilidad de expresarse con libertad.

Por qué comentarios

Miles de programadores (bueno, quizá más bien unos veinte) no tienen mayor preocupación que su aparición como coautor en este artículo. Por este motivo evitan el uso de comentarios en su código. Mientas tanto disfrutan el resultado simple y exacto de cada función, que devuelve 3 cuando el parámetro var1 es “OK” y var2 guarda 15. Tres significa que la máquina va a arrancar, el robot gira a la izquierda, el programa va a terminar o el contrario de esto – o todo a la vez o una combinación arbitraria de esto. Depende del contexto, el cual puedes encontrar 150 líneas más arriba o en otro fichero del programa. Mala suerte, si la función está mal y debería devolver 4, que es algo diferente que 3 o lo mismo. Depende del contexto. Hay muchas maneras de escribir código inmantenible.

No te entiendo

Usando comentarios trae la cuestión de lo que es un buen comentario. En general, yo consideraría un bueno comentario alto que explica la semántica y no la sintaxis. Alguien que sabe programar no necesita un comentario como

// Incrementa x en uno
x = x + 1

Sin embargo, es un comentario obligatorio cuando sería el único en una función de 1500 líneas.

Explicar la semántica puede ser difícil a veces. A continuación sigue una lista con ejemplos de la vida real, que muestran lo que no es probablemente un buen comentario.

bool ProcesaTeclaUsuario(void)
// de momento es global por problemas con los punteros

En este programa no hubo ninguna función no-global. Pero, por supuesto, puede haber una razón de no ser global diferente para cada función.

num_mens_control++;  //TODO tiene sentido???

¿Tiene sentido lo que haces ahí? Mientras funciona, todo tiene sentido. En este contexto me es grato presentar la definición

Un científico sabe por qué no funciona. Un ingeniero no sabe, por qué funciona.

Mientras cambias código y no estás seguro si el cambio fue bueno, puedes dejar las líneas originales comentadas y marcar la modificación con una palabra especial. Si tienes mucho que cambiar, entonces un poco de variación puede resultar más gratificante. Estos ejemplos son de un fichero con unos 2000 líneas:

//TODO
//XXX TODO
//WORKAROUND
//WORKAROUND TO DO IT BETTER
//XXX BAUSTELLE
//XXX BAU 28.06

Baustelle es alemán para “obras”. El aviso “constantemente en obras” en una página web es igualmente significativo. Quién esperaría que una página web cambiase.

!! rules necesarias para el correcto funcionamiento:
rule void Nr_Set_Visible_Displayed(object Ob_Strip input)

A diferenciar de las rules no necesarias y las rules para el funcionamiento incorrecto.

!!  start of Md_GbMDW_FPL needed rules

¿Escribes código que no es needed?

!! END OF RULE EXPERIMENTAL

Vale. Lo haces.

Cuando la comunicación falla, todavía te queda decir a otros lo que deben hacer por código fuente.

!! Note: move this(Ob_GbManCoord) to strip model.
export variable object Ob_GbManCoord;

Por supuesto, lo podrías hacer tú mismo, pero ¿por qué?

!! New model for waypoints line
model MdGb Md_Gb_Waypoints

O este comentario es actualizado frecuentemente o este modelo será nuevo para siempre.

!! Study assigment of colours
if Ob_Fp_Strip.In_Flag_Un_Flag_Field then

A veces, un ordenador toma un respiro se pregunta: ¿En qué color debería pintarlo?

!! Rule to solve the STR-1207: Panning in Playback mode

Resuelto. Una vez y por todas. Ni piensas en que este código podría ser útil para otro propósito.

//declarar el objeto, es importante inicializarlo a NULL
TStringList *Valores = NULL;
Valores = new TStringList; //crear instancia del objeto

Esto es un comentario importante. De otra forma el lector podría llegar a pensar que no vale la pena asignar NULL a un puntero que será sobrescrito inmediatamente después.

Como comentar mejor

En general podrías tener en cuenta las siguientes ideas para escribir un código.

  • Como un programador ya sabe el lenguaje de programación, no necesitas explicárselo de nuevo. Una excepción sería si usaste el lenguaje de una forma rara y sorprendente como, por ejemplo, sobrecargar el operador + sin la connotación de “más”. No obstante, en este caso deberías considerar cambiar el código y no el comentario.
  • No repitas código en tus comentarios. “Añadir cinco a x” no aporta ninguna información nueva a “x + 5”. Céntrate en el significado de x, por ejemplo “añade 5 metros a la posición x.
  • No olvides que identificadores (variables, tipos y nombres de funciones) ya deberían contener su semántica en si mismos. Un comentario puede todavía ser necesario para explicar el contexto en que una operación tiene lugar, por ejemplo un comentario a send_to_printer(document) podría ser “Aquí el documento debe estar en un formato adecuado para la impresora”.
  • ¿Tiene importancia cuando el código o el comentario fue escrito y cuantas veces fue cambiado? Ten esto en cuenta antes de escribir una fecha en el código. “Nuevo” y “viejo” dan una idea de que algo fue cambiado, pero no cuando. No obstante, no tengas miedo en que comentarios podrían caducar en el próximo cambio de código. Todavía pueden dar una pista importante y un programador sabe que lo que hace un programa funcionar es el código y no el comentario.
  • No olvides limpiar el código. Muchos de los ejemplos anteriores se “olvidaron”. Eran marcadores durante el desarrollo que perdían su sentido cuando el trabajo concluyó.
  • Si tus ficheros usan una cabecera, sólo escribe cosas ahí para que habrá suficiente disciplina para actualizarlas. Un fichero guarda una fecha de última modificación, el último “autor” es probablemente uno de tu grupo de trabajo, y la versión del fichero fuente inútil. Un fichero ejecutable tiene un número de versión y todos los ficheros fuente para crearlo tienen este mismo número de versión automáticamente. A menos si vendes ficheros fuentes y no programas que funcionan.
  • No es mala idea de usar comentarios para separar código visualmente en secciones (con barras o incluso con títulos). Es sabio usar el mismo estilo para el mismo tipo de sección.

Referencias