El comentario dice que user_profile es un dict plano con campos age, weight, height, pero la implementación actual recibe un objeto UserProfile (dataclass). La función accede a user_profile.bmi_index y user_profile.health_goals, campos que no existen en el dict documentado.
# Args:
# user_profile (dict): user data
# Keys: age, weight, height
# Returns: float score 0-100
def calculate_nutrition_score(
user_profile: UserProfile,
...
):
score += user_profile.bmi_index
goals = user_profile.health_goals
Corrección: Actualizar el docstring para documentar el tipo UserProfile y sus atributos relevantes: bmi_index, health_goals, dietary_restrictions.
El comentario declara "Returns: bool — True si el plan es válido", pero la función devuelve un objeto ValidationResult con campos .is_valid, .errors[] y .warnings[]. Cualquier consumidor que confíe en el comentario fallará silenciosamente al usar el resultado como booleano.
# Returns:
# bool: True if meal plan is valid,
# False otherwise
return ValidationResult(
is_valid=passed,
errors=error_list,
warnings=warn_list
)
Corrección: Documentar el tipo de retorno correcto ValidationResult y sus campos. Añadir ejemplo de uso mostrando result.is_valid.
El comentario indica explícitamente "This function is pure — no DB calls", pero la implementación actual hace db.query(FoodTable) para enriquecer los macros con datos de referencia del USDA cargados en la base de datos. Afirmación completamente falsa que puede llevar a tests unitarios incorrectos.
Corrección: Eliminar la afirmación de pureza. Documentar que la función consulta FoodTable en DB y que por tanto requiere contexto de base de datos en tests.
El comentario describe la fórmula de Harris-Benedict clásica (1919) con los coeficientes originales. La implementación usa la revisión de Mifflin-St Jeor (1990), que tiene coeficientes distintos. Error grave para auditores clínicos o regulatorios que validen la lógica de negocio.
Corrección: Reemplazar la descripción de la fórmula. Añadir referencia: Mifflin MD, et al. Am J Clin Nutr. 1990.
El comentario de bloque dice "Ver legacy_scoring.py para el algoritmo previo v1.x". El archivo fue eliminado hace 14 meses (commit a3f8c12). La referencia genera confusión en desarrolladores nuevos que buscarán un archivo inexistente.
Corrección: Eliminar la referencia o reemplazar por un enlace al commit o PR que introdujo el algoritmo actual.
Comentario: "Results are cached in Redis with 1h TTL". La integración Redis fue reemplazada por @lru_cache(maxsize=512) hace 8 meses por cuestiones de infraestructura. No hay TTL de 1 hora; la caché vive con el proceso.
Corrección: Actualizar a: "Results are cached in memory (lru_cache, per-process, no TTL). Cache is invalidated on service restart."
El comentario menciona "Calls /api/v1/sync". El endpoint actual es /api/v3/wearable/ingest. El v1 fue desactivado en producción en enero 2025.
Corrección: Actualizar la referencia al endpoint correcto e indicar la versión de la API.
La función puede lanzar NutritionalDataError si el alimento no existe en la base de datos USDA, y RateLimitError si se superan las consultas por minuto. Ninguna de las dos excepciones está documentada en el docstring. Los integradores no podrán manejar estos errores correctamente.
Corrección: Añadir sección Raises: documentando ambas excepciones con las condiciones que las provocan.
La función escribe en la tabla audit_log cada vez que se modifican las metas del usuario (requerimiento regulatorio). El docstring solo dice "updates user goals". Consumidores en tests de integración que no mockeen la tabla de audit recibirán errores de FK.
Corrección: Documentar el efecto secundario: "Side effect: writes to audit_log table (regulatory requirement — do not disable)."
La función implementa retry exponencial con hasta 3 intentos y backoff de 2^n segundos. Esto puede causar latencias de hasta ~7 segundos en caso de timeout del modelo. El comentario solo dice "calls the AI model API". Crítico para diseñadores de SLAs.
Corrección: Documentar la política de reintentos, el backoff máximo y el timeout total esperado en el peor caso.
La clase usa estado mutable compartido (self._session_cache) sin locks. No es thread-safe. El comentario de clase no advierte de esta limitación, lo que podría causar race conditions en deployments con workers múltiples.
Corrección: Añadir advertencia explícita: "Warning: Not thread-safe. Instantiate one engine per worker process."
Cuando food_list está vacía, la función devuelve [] silenciosamente en lugar de lanzar una excepción. Comportamiento correcto pero sorprendente. No está documentado, llevando a integradores a añadir guards innecesarios o a asumir que lanza excepción.
Corrección: Añadir nota: "Returns empty list if food_list is empty. No exception raised."