Una función puede funcionar perfectamente y, aun así, obligarte a releer todo su cuerpo para recordar cómo usarla. En proyectos pequeños quizá no moleste; unas semanas después sí.
En esta lección vas a añadir dos señales para el lector: una docstring que explica la intención y type hints que muestran qué tipos de datos se esperan.
Leer una firma y una docstring y responder qué recibe, qué devuelve y qué hace la función.
La firma puede contar parte de la historia
def crear_saludo(nombre):
return f"Hola, {nombre}"Sabes que recibe algo llamado nombre, pero la función no dice explícitamente si espera texto, un número o cualquier otra cosa.
def crear_saludo(nombre: str) -> str:
return f"Hola, {nombre}"nombre: str comunica «aquí espero texto» y -> str comunica «mi resultado normal es texto». Eso mejora la lectura y ayuda a editores y analizadores.
Una anotación orienta; Python no la convierte en una barrera
Es fácil interpretar los type hints como una regla que Python hará cumplir. No funciona así: por sí solos son metadatos.
def duplicar(texto: str) -> str:
return texto * 2
print(duplicar(3))Este código imprime 6. Python no detiene la llamada solo porque 3 sea un entero. Más adelante podrás usar herramientas que detecten esa incoherencia antes de ejecutar, pero la anotación no cambia la lógica de la función.
Modelo mental: piensa en los type hints como etiquetas en una caja. Ayudan a saber qué debería haber dentro; no ponen un candado.
La docstring responde al «para qué» que la firma no puede expresar
def calcular_total(precio: float, unidades: int) -> float:
"""Devuelve el coste de varias unidades sin aplicar descuentos."""
return precio * unidades
print(calcular_total(4.5, 3))La docstring va inmediatamente después de def. No necesita repetir cada palabra de la firma. Su valor está en aclarar la intención, alguna condición relevante o un comportamiento que no sea obvio.
Evita descripciones como «función que calcula el total» si el nombre ya dice eso. Una buena docstring añade información.
Decide qué merece explicación y qué solo necesita un buen nombre
No conviertas cada función de tres líneas en un documento enorme. Para una función sencilla, una frase puede bastar. Añade más detalle cuando existan reglas que el lector no pueda deducir fácilmente: unidades de medida, casos límite, excepciones esperadas o efectos secundarios.
¿Tengo que anotar y documentar absolutamente todo?
No para aprender. Empieza por funciones públicas o reutilizables y por aquellas cuyo uso no sea evidente. La documentación debe reducir dudas, no añadir ruido.
Haz visible el contrato de una función
En esta lección solo necesitas responder tres preguntas al leer una función: ¿qué recibe?, ¿qué devuelve?, ¿qué hace?. El análisis estático se trabajará más adelante, en la lección 41.
nombre: strstrAñade anotaciones básicas y una docstring breve. La lógica ya funciona: no la cambies.
Hola, Ada
La salida aparecerá aquí.
Necesito una pista
- Anota el parámetro como
nombre: stry el retorno como-> str. - Dentro de la función, una docstring va entre triples comillas justo después de la cabecera.
Ver una solución razonada
def saludar(nombre: str) -> str:
"""Crea un saludo para una persona."""
return f"Hola, {nombre}"
print(saludar("Ada"))La confusión que conviene evitar desde hoy
«Si tiene type hints, los datos ya están validados» es una conclusión incorrecta. Validar significa comprobar una condición durante la ejecución y decidir qué hacer si no se cumple.
Los hints documentan el contrato esperado. Esta distinción te será útil en la siguiente lección, donde sí aprenderás a reaccionar ante problemas que ocurren al ejecutar.
Tu criterio para dejar esta lección atrás
- Puedes explicar con tus palabras qué información aporta
nombre: str. - Sabes que
-> floatdescribe el retorno esperado, no lo fuerza. - Puedes escribir una docstring de una frase que aporte algo que el nombre no cuenta.
Si puedes leer una firma anotada y distinguir documentación de validación, ya tienes la base necesaria.