Definición y Type Hints

Ningún almacén eficiente funciona explicando cada tarea desde cero cada vez que alguien llega al turno. Se escribe un Procedimiento Operativo Estándar (SOP) y se le dice al operario: “Ejecuta el protocolo X”. El protocolo existe, ya tiene nombre, y hace lo que tiene que hacer.

En Python, esos protocolos son las Funciones: un bloque de código con nombre propio, diseñado para una sola tarea. Lo escribes una vez y, cada vez que lo llamas, sabes exactamente qué va a hacer.

Fig. 9.2: Una función, un solo trabajo.

Anatomía de un Protocolo

La palabra clave que arranca todo es def. En este Almacén Digital, además, seguimos la norma ISO de calidad: siempre declaramos qué entra y qué sale, sin ambigüedades.

# Esquema visual (no lo copies tal cual: la sangría inicial no es válida)
#  INICIO           NOMBRE     ( ENTRADA : TIPO ) -> SALIDA :
   def              duplicar   ( numero  : int  ) -> int    :
       """Documentación: Multiplica la entrada por dos."""
       resultado = numero * 2
       return resultado

Fig. 9.3: La firma de una función de cerca.

Desglose de Piezas:

1. def: La señal de alerta. “Atención, estoy definiendo un nuevo procedimiento”.
2. duplicar: El nombre del procedimiento. Verbo por regla general (calcular, enviar, procesar); si devuelve un bool, pregunta: es_valido, tiene_stock.
3. numero: int: El parámetro. Le dice a Python: “Para que esto funcione, necesito que me des un Entero”.
4. -> int: La promesa. “Prometo que, cuando termine, te devolveré un Entero”.
5. return: La entrega final. Aquí termina el trabajo y se entrega el producto.

Nota: numero: int es una promesa para quien lee el código, tu editor y herramientas como mypy, no un candado que Python revise al ejecutar:

def duplicar(numero: int) -> int:
    return numero * 2

print(duplicar("5"))  # "55", sin ningún error

Le pedimos un entero y le mandamos el texto "5". Python no se queja: multiplicar texto por 2 lo repite, así que el resultado es "55", no 10. Quien atrapa este desliz es tu editor o un verificador de tipos, nunca el propio Python en tiempo de ejecución.

La Etiqueta del Procedimiento (Docstring)

La cadena entre triples comillas justo debajo del def es el docstring: la descripción oficial del procedimiento, pegada al procedimiento mismo. Python la guarda, así que cualquiera (tú incluido, en unos meses) puede consultarla sin abrir el archivo:

help(duplicar)
# duplicar(numero: int) -> int
#     Documentación: Multiplica la entrada por dos.

La convención de este libro: una línea, en presente, que diga QUÉ hace la función (el cómo ya lo dice el código). Todas las funciones del proyecto final la llevan.

Ejemplo Real

def calcular_iva(precio: float) -> float:
    """Calcula el 16% de impuesto."""
    return precio * 0.16

# Ejecutando el procedimiento (Llamada)
impuesto = calcular_iva(100.0)
print(f"El impuesto es: {impuesto}")

¿Cuándo conviene escribir una función?

Saber escribir una función no responde la pregunta más útil: ¿cuándo vale la pena? Encerrar tres líneas en un def no siempre mejora el código, y al revés, dejar todo suelto en un solo bloque gigante es como tener el almacén operando sin un solo procedimiento escrito. Hay tres señales claras de que llegó el momento.

La copiaste. Si te encuentras pegando las mismas líneas en dos lugares, ese es el aviso. El día que cambie la regla (el IVA sube al 18%) vas a tener que cazar cada copia. Una función la deja en un solo sitio: la corriges una vez y todo el almacén obedece.

Le puedes poner nombre. Si un bloque de código hace algo que sabrías explicar en una frase (“esto valida el correo”, “esto calcula el envío”), esa frase es el nombre de la función. Un buen nombre convierte diez líneas crípticas en una sola instrucción legible: validar_correo(texto). El código se lee como lo que hace, no como cómo lo hace.

Quieres probarlo por separado. Una tarea metida dentro de otra tarea no se puede revisar sola. Sacada a su propia función, la puedes llamar con datos de prueba y confirmar que entrega lo correcto sin arrancar todo el programa.

El caso contrario también tiene su regla: no envuelvas en una función algo que se usa una sola vez, es trivial, y se entiende mejor escrito tal cual. Una función que solo se llama una vez y no aclara nada es burocracia: un SOP para “abrir la puerta”. El criterio real es si ponerle nombre y frontera hace el código más fácil de leer y de cambiar.