Comentar el código: cuándo y cómo

Los comentarios son notas dentro del código que el ordenador ignora, escritas para las personas que lo lean (a veces, tú dentro de seis meses). Escribirlos bien ahorra tiempo; escribirlos mal lo hace perder.

Cómo se escriben

Cada lenguaje tiene su sintaxis:

• Python: # comentario
• JavaScript, Java, C#: // comentario para una línea y /* ... */ para varias.
• HTML: <!-- comentario -->
• SQL: -- comentario

Qué hace un buen comentario

La regla más útil: el código dice qué hace; el comentario dice por qué.

# Mal: repite lo que ya dice el código
total = total + 1   # suma 1 al total

# Bien: explica una decisión que el código no deja ver
# La API devuelve la página 0 vacía, así que empezamos en la 1
pagina = 1

Comentarios que sí aportan:

• El motivo de una decisión no evidente o de una solución provisional.
• Una advertencia («no cambiar el orden: el servidor lo exige»).
• Una referencia a un enlace, una norma o un fallo conocido.
• La descripción de una función o módulo: qué hace, qué recibe y qué devuelve.

Cuándo es mejor no comentar

Si necesitas un comentario para explicar qué hace una línea, a veces lo mejor es reescribirla:

• Usa nombres claros. precio_con_iva explica más que x con un comentario al lado.
• Divide las funciones largas en otras más pequeñas con un nombre que diga lo que hacen.
• No dejes código antiguo comentado: con un sistema de control de versiones como Git puedes recuperarlo cuando quieras.

El peor enemigo: el comentario desactualizado

Un comentario que ya no corresponde al código es peor que no tener ninguno, porque engaña. Cuando cambies el código, revisa los comentarios de alrededor. Si un comentario se vuelve difícil de mantener, es una señal de que el código necesita simplificarse.

Etiquetas útiles

Muchos equipos usan marcas como TODO (pendiente), FIXME (arreglar) o NOTE para localizar fácilmente lo que queda por hacer. Úsalas con fecha o con una descripción clara, y revísalas de vez en cuando para que no se acumulen.