En un proyecto que crece, es normal que queden restos: funciones que ya no se llaman, imports abandonados, comentarios que describen una versión vieja del código y tareas pendientes que nunca se revisan. Todo eso aumenta ruido y dificulta entender qué parte del sistema sigue siendo importante.
En este tema aprenderemos a detectar código muerto, comentarios engañosos y deuda técnica visible. También veremos cómo limpiar de forma segura usando pruebas y herramientas como Ruff.
Código muerto es código que permanece en el proyecto, pero ya no se ejecuta o no tiene efecto real. Puede aparecer como funciones no usadas, ramas imposibles, variables sobrantes, imports abandonados o bloques comentados.
def calcular_total(productos):
subtotal = sum(
producto["precio"] * producto["cantidad"]
for producto in productos
)
descuento = 0
return subtotalEn este ejemplo, descuento se asigna pero no se usa. Esa línea no aporta comportamiento y agrega ruido.
El código muerto hace que el lector dude. Si una función existe, parece que alguien la necesita. Si un bloque comentado queda en el archivo, parece que podría volver. Esa duda aumenta el costo de mantenimiento.
También puede ocultar errores: una variable sin usar puede indicar que una regla quedó incompleta, no simplemente una línea sobrante.
Ruff puede detectar muchos casos simples de código muerto.
import os
import json
def obtener_total(productos):
cantidad = len(productos)
return sum(producto["precio"] for producto in productos)En este fragmento, os, json y cantidad no se usan. Ejecuta:
python -m ruff check src testsRuff puede marcar imports no usados y variables asignadas sin uso.
Si una variable no se usa, no siempre significa que haya que borrarla inmediatamente. Primero pregunta si representa una regla incompleta.
def calcular_total(productos, cliente):
subtotal = calcular_subtotal(productos)
descuento = obtener_descuento(cliente)
return subtotalAquí descuento no se usa. Tal vez sobra, o tal vez falta aplicar el descuento. El diagnóstico requiere leer intención y pruebas.
El código comentado suele quedar como recuerdo de una versión anterior. En la práctica, casi siempre molesta más de lo que ayuda.
def obtener_descuento(cliente):
if cliente == "vip":
return 0.15
# if cliente == "premium":
# return 0.20
return 0Si esa regla no está activa, conviene eliminar el bloque comentado. Si es una tarea pendiente real, debe registrarse de manera explícita y verificable.
Un comentario engañoso es peor que la falta de comentario, porque empuja al lector hacia una interpretación equivocada.
# Aplica un descuento del 10%.
def aplicar_descuento(total):
return total * 0.85El comentario dice 10%, pero el código aplica 15%. Una mejora es nombrar la constante y eliminar el comentario falso.
DESCUENTO_VIP = 0.15
def aplicar_descuento(total):
return total * (1 - DESCUENTO_VIP)Un comentario no debería repetir lo que el código ya dice.
# Incrementa el total con el costo de envío.
total += COSTO_ENVIOEse comentario no agrega información. Es mejor reservar comentarios para decisiones no evidentes.
# El envío se cobra aunque el producto sea digital por una regla comercial temporal.
total += COSTO_ENVIOLos comentarios TODO pueden ser útiles si son concretos, pero se vuelven deuda invisible cuando no tienen contexto, fecha, responsable o enlace a una tarea.
Poco útil:
Más útil:
Si el equipo usa un sistema de tareas, suele ser mejor registrar la deuda allí y dejar el código lo más limpio posible.
La deuda técnica visible aparece cuando el código muestra señales claras de decisiones temporales o incompletas:
temporal, nuevo, viejo o fix.def calcular_impuesto_temporal(pais):
# Por ahora todos pagan esto.
return 0.21El problema no es solo el valor fijo. El nombre y el comentario avisan que hay una decisión temporal sin resolver. Una mejora mínima sería hacer explícita la regla actual:
IMPUESTO_PREDETERMINADO = 0.21
def obtener_impuesto(pais):
return IMPUESTO_PREDETERMINADOSi realmente falta una regla por país, conviene crear una tarea concreta para incorporarla.
Antes de eliminar código, conviene seguir una secuencia:
python -m ruff check src tests
python -m pytestEn el proyecto ventas_demo, crea temporalmente este archivo src/deuda.py:
import os
def calcular_total_temporal(productos):
# TODO: revisar
total = 0
cantidad = len(productos)
for producto in productos:
total += producto["precio"] * producto["cantidad"]
# total = total * 1.21
return totalLuego ejecuta:
python -m ruff check src/deuda.pyIdentifica qué puede detectar Ruff y qué requiere criterio humano.
Una limpieza posible es:
def calcular_total(productos):
total = 0
for producto in productos:
total += producto["precio"] * producto["cantidad"]
return totalEliminamos el import no usado, la variable sin uso, el comentario impreciso y el bloque comentado. También quitamos la palabra temporal del nombre porque no aporta información útil.
No toda deuda puede resolverse en el momento. Si decides dejar una nota, debe ser concreta y accionable.
Evita:
Prefiere:
Limpia el siguiente código:
import json
import os
def procesar(datos):
# Esta función calcula el promedio
total = 0
contador = 0
debug = True
for item in datos:
total += item["valor"]
contador += 1
# print(total)
return totalSeñales a revisar:
debug no usada.contador no usada.def calcular_total(datos):
total = 0
for item in datos:
total += item["valor"]
return totalSi la intención real era calcular promedio, entonces la solución sería diferente. Por eso primero hay que confirmar el comportamiento esperado.
Busca en ventas_demo señales de código muerto o deuda visible. Realiza estas tareas:
src y tests.python -m ruff check src tests
python -m pytestAntes de continuar, verifica que puedes hacer lo siguiente:
En este tema vimos que el código muerto, los comentarios engañosos y la deuda técnica visible aumentan ruido y reducen confianza. Limpiar estos elementos no es solo embellecer: es facilitar que el próximo cambio se haga con menos dudas.
En el próximo tema estudiaremos variables temporales innecesarias y estados intermedios confusos.