English

Nunca dejes código comentado

Deja de comentar código viejo. Tu historial de git ya lo recuerda, y tu asistente de IA se confunde con las líneas muertas. Cada bloque que guardas "por si acaso" es un bloque que git ya guarda — perfectamente, para siempre, con el mensaje de commit que explica por qué cambió. La copia comentada no aporta nada más que ruido, dudas y peores sugerencias de la IA.

Por qué el código muerto es peor que ningún código

• Los humanos dudan. Robert C. Martin lo señaló en Clean Code: quien ve ese código comentado no se atreve a borrarlo. Nadie sabe si es importante, así que sobrevive revisión tras revisión y se pudre en silencio.
• Miente con el tiempo. El código vivo a su alrededor sigue cambiando; el bloque muerto no. En semanas ya referencia variables que no existen y lógica que ya no aplica.
• Tu asistente de IA lo lee como contexto. Un agente de código no se salta el texto gris. El código comentado ocupa la ventana de contexto del modelo como cualquier otro token, y puede anclar al modelo en enfoques abandonados: firmas de funciones viejas, parámetros muertos, la API de la que ya migraste. Estás pagando tokens para empeorar las sugerencias.
• Los analizadores estáticos lo marcan. SonarSource incluye la regla S125 — "Sections of code should not be commented out" — para Java, Python, TypeScript, C++ y más. Si los linters lo tratan como un code smell, trátalo tú igual.

La solución: borra, haz commit y sigue

- # def calculate_discount_v1(price, tier):
- #     # old logic, keep for reference
- #     if tier == "gold":
- #         return price * 0.8
- #     return price
  def calculate_discount(price, tier):
      return price * DISCOUNT_BY_TIER.get(tier, 1.0)

Borra el bloque y escribe un mensaje de commit honesto: refactor: replace tiered discount branches with a lookup table. Ese mensaje es la "referencia": buscable, con fecha, con autor y unido exactamente al código que describe.

Reglas prácticas

La línea divisoria: los comentarios que explican por qué son documentación; los comentarios que contienen qué (código ejecutable) son peso muerto.

Nivel avanzado: git como tu papelera de reciclaje

El miedo detrás del código comentado es "no lo voy a encontrar nunca más". El pickaxe de git elimina ese miedo:

# Find every commit that added or removed a string
git log -S "calculate_discount_v1" --oneline

# Same, but match a regex against changed lines
git log -G "discount.*tier" --oneline

# Trace the full history of a function, even after it was deleted
git log -L :calculate_discount:pricing.py

# Resurrect one file exactly as it was in an old commit
git show a1b2c3d:src/pricing.py > /tmp/old_pricing.py

-S (el "pickaxe") encuentra commits que cambiaron el número de ocurrencias de una cadena — que es exactamente lo que hace un borrado. -L rastrea un rango de líneas o una función a través de la historia. El código borrado no desaparece: queda indexado.

Bonus para flujos con IA: corre tu agente sobre un archivo limpio y sobre el mismo archivo con los bloques muertos. La versión limpia recibe respuestas más enfocadas, porque cada token del contexto es verdad viva y actual.

Recursos

• Clean Code Tip #7: Clean Up Old Commented-Out Code — Robert C. Martin (InformIT)
• Code Smell 151: Commented Code — Maximiliano Contieri
• Dead Code — Refactoring.Guru code smells
• Documentación de git-log — búsqueda histórica con -S, -G y -L
• Regla S125 de SonarSource: Sections of code should not be commented out

Read this article in English