Funciones de Python

Una función es un bloque de código con nombre que realiza una tarea. Las funciones incorporadas como print() e input() ya te ofrecen tareas útiles que puedes llamar; def te permite crear las tuyas. Un buen nombre convierte varias líneas de trabajo en una llamada que indica qué quieres hacer.

Escribe la cabecera y el cuerpo

def greet():
    print("Hello!")
    print("Welcome to Python.")

greet()
greet()

La cabecera empieza con def, seguido del nombre, los paréntesis y los dos puntos. Las líneas con sangría forman el cuerpo. Usa cuatro espacios por cada nivel de sangría. Las líneas greet() sin sangría están fuera de la función, así que son llamadas del programa principal.

Cuando Python llega a la definición, crea la función y le da el nombre greet. Todavía no muestra ninguno de los mensajes. La primera llamada empieza en la primera línea del cuerpo y muestra «Hello!» seguido de «Welcome to Python.». La segunda vuelve a iniciar el cuerpo y muestra las mismas dos líneas. Hay cuatro líneas de salida en total.

Un nombre y una llamada son distintos

Los paréntesis de greet() lo convierten en una llamada, aunque esta función no necesite entradas. Una línea que solo contiene greet hace referencia a la función y no ejecuta nada. print(greet) muestra una descripción del objeto de función, incluida una dirección de memoria; no ejecuta el saludo.

Python debe haber ejecutado una definición antes de que una llamada use su nombre. Si un archivo empieza con greet() y define greet después, la primera línea lanza NameError: name 'greet' is not defined. Coloca la definición antes de la llamada del nivel superior.

Elige nombres que expliquen la tarea

Usa palabras en minúsculas unidas por guiones bajos, como print_receipt o convert_to_miles. Los nombres pueden contener letras, dígitos y guiones bajos, pero no pueden empezar por un dígito ni ser una palabra reservada como return. Los nombres distinguen entre mayúsculas y minúsculas: greet y Greet son nombres distintos.

Mantén disponibles los nombres incorporados. Después de input = "yes", el nombre input hace referencia a texto, así que input("Name? ") lanza TypeError: 'str' object is not callable. Llamar answer a la variable mantiene accesible la función incorporada.

Corrige primero la estructura

La ausencia de los dos puntos en la cabecera produce SyntaxError: expected ':'. Un cuerpo vacío o sin sangría produce un IndentationError. Una función que aún se está planificando necesita una sentencia; pass es un marcador provisional que no hace nada:

def print_receipt():
    pass

print_receipt()

Este programa se ejecuta sin salida. La llamada llega a pass y después al final del cuerpo. Sustituye el marcador provisional por la tarea real cuando vayas a implementarla. Si una línea debía pertenecer al cuerpo pero se ejecuta en un momento incorrecto, comprueba su sangría antes de modificar la llamada.

Un programa con funciones no ejecuta todos los cuerpos en el orden en que aparecen en la página. Una llamada cambia el flujo de ejecución: Python entra en la función llamada, termina su tarea y reanuda el código que la llamó justo después de esa llamada.

Sigue una llamada dentro de otra

def line():
    print("----------")

def banner():
    line()
    print("  REPORT")
    line()

print("Start")
banner()
print("End")

Primero, Python define line y banner. No se ejecuta ninguno de los cuerpos. La siguiente sentencia muestra «Start». La llamada a banner() entra en su cuerpo, cuya primera sentencia llama a line().

Python entra ahora en line, muestra «----------» y llega al final. Vuelve a la siguiente sentencia de banner, que muestra « REPORT». La segunda llamada a line() muestra otra línea de guiones. Por último, termina banner, así que el programa principal se reanuda y muestra «End».

La salida es:

Start
----------
  REPORT
----------
End

Lleva un registro de las llamadas sin terminar

Mientras se ejecuta line, banner espera a que termine. El programa principal también espera a banner. Python registra estas llamadas sin terminar en la pila de llamadas. La llamada activa más interna termina primero, y cada código que realiza una llamada se reanuda en su siguiente sentencia.

Para seguir la ejecución en papel, numera las líneas del programa. Anota una línea del cuerpo solo cuando la ejecución llegue a ella mediante una llamada. En cada llamada, marca dónde se debe reanudar. Escribe la salida cuando se ejecute su print, conservando espacios y saltos de línea. Así separas la ruta que sigue el código de la salida que produce.

Define las funciones auxiliares antes de necesitarlas

La definición de una función auxiliar puede aparecer debajo de la definición de la función que la llama:

def show_report():
    draw_line()
    print("Ready")

def draw_line():
    print("====")

show_report()

Esto funciona porque ambas definiciones se han ejecutado antes de que la llamada final entre en show_report. Python busca draw_line cuando el cuerpo la llama realmente. Mover show_report() por encima de def draw_line(): haría que la llamada fallara al intentar usar la función auxiliar aún no definida.

Las llamadas repetidas empiezan de nuevo

Una llamada dentro de un bucle entra en el cuerpo en cada repetición:

for i in range(3):
    line()

Con la primera definición de line, esto muestra la línea de guiones tres veces. La función empieza en la primera sentencia de su cuerpo en cada llamada.

Si una llamada falla, Python muestra una traza de la excepción. Su última línea indica el tipo de error y el mensaje. Las entradas de llamadas anteriores van desde la llamada sin terminar más externa hasta la línea que falló. Leer primero el error final y después revisar la línea más interna y el código que la llamó te ayuda a localizar tanto la operación que falla como la ruta que le proporcionó los datos.

Una función puede reutilizarse con distintas entradas cuando su cabecera da nombre a los valores que necesita. Estos nombres son parámetros. El código que realiza la llamada proporciona argumentos, que son los valores concretos usados en una llamada determinada.

Asocia valores a nombres

def rectangle_area(width, height):
    print("Area:", width * height)

rectangle_area(4, 2.5)
rectangle_area(3, 7)

Los parámetros son width y height. En la primera llamada, los argumentos son 4 y 2.5. Los argumentos posicionales se asocian de izquierda a derecha: width recibe 4 y height recibe 2,5. El cuerpo muestra «Area: 10.0». La siguiente llamada da valores nuevos a los mismos nombres de parámetros y muestra «Area: 21».

Cada parámetro actúa como una variable dentro de esa llamada. No necesitas asignar valores a width y height antes; la llamada los proporciona. Una función sin parámetros también necesita paréntesis vacíos tanto en su definición como en sus llamadas.

El orden puede cambiar el significado

def describe_pet(animal, name):
    print(name, "is a", animal)

describe_pet("cat", "Milo")
describe_pet("Milo", "cat")

La primera llamada muestra «Milo is a cat». La segunda muestra «cat is a Milo». Ambas llamadas son válidas en Python, así que ningún error señala el cambio de significado. Lee el orden de la cabecera antes de elegir argumentos posicionales, sobre todo cuando varios parámetros aceptan el mismo tipo de valor.

Los argumentos pueden ser expresiones

Python evalúa cada expresión de argumento antes de iniciar el cuerpo. Con side = 6, la llamada rectangle_area(side, side) pasa 6 dos veces y muestra «Area: 36». El nombre de la variable del código que realiza la llamada no tiene que coincidir con ninguno de los nombres de los parámetros. La llamada rectangle_area(side + 1, 2) pasa 7 y 2; no pasa el texto «side + 1».

Interpreta un error en el número de argumentos

Cada parámetro sin valor predeterminado necesita un argumento. Con la función de área anterior:

La primera lanza TypeError: rectangle_area() missing 1 required positional argument: 'height'. La segunda lanza TypeError: rectangle_area() takes 2 positional arguments but 3 were given. Revisa la cabecera de la función indicada y después cuenta cómo la llamada ocupa sus parámetros.

Pasa el tipo de valor que necesita la tarea

Python no exige un tipo solo porque un parámetro se llame width. rectangle_area("4", 2) muestra «Area: 44» porque multiplicar texto por un entero repite ese texto. Como input() devuelve texto, convierte la entrada numérica antes de pasarla:

width = float(input("Width: "))
rectangle_area(width, 2)

Aquí, float() convierte el texto introducido en un número antes de que lo reciba la función de área.

Un argumento por palabra clave nombra en la llamada su parámetro de destino. Esto facilita la lectura de una llamada cuando varios valores podrían confundirse. Python asocia la palabra clave con el nombre de la cabecera en lugar de usar su posición.

Asocia por nombre

def describe_pet(animal, name):
    print(name, "is a", animal)

describe_pet(name="Milo", animal="cat")
describe_pet(animal="cat", name="Milo")

Ambas llamadas muestran «Milo is a cat». El orden de los argumentos por palabra clave puede cambiar porque cada valor indica el parámetro que ocupa. La misma idea hace que rectangle_area(width=4, height=2.5) sea legible sin comprobar qué dimensión iba primero.

Una palabra clave no es una variable nueva en el código que realiza la llamada. En describe_pet(name="Milo", animal="cat"), name= dirige «Milo» al parámetro. No asigna «Milo» a una variable del nivel superior llamada name. Escribe los argumentos por palabra clave sin espacios alrededor de =, siguiendo el estilo habitual de Python.

Combina argumentos posicionales y por palabra clave

describe_pet("cat", name="Milo")

El primer argumento ocupa animal por posición. La palabra clave ocupa name, así que cada parámetro recibe exactamente un valor. Los argumentos posicionales deben ir primero. La llamada describe_pet(name="Milo", "cat") se rechaza con SyntaxError: positional argument follows keyword argument.

Para revisar una llamada combinada, ocupa las posiciones de izquierda a derecha y después asocia las palabras clave. Comprueba que ninguna posición se ocupe dos veces y que no quede vacía ninguna obligatoria.

Corrige las palabras clave duplicadas o desconocidas

El duplicado lanza TypeError: describe_pet() got multiple values for argument 'animal'. El nombre mal escrito lanza TypeError: describe_pet() got an unexpected keyword argument 'nmae'. Compara los nombres carácter a carácter; las mayúsculas y minúsculas también importan. Cambiar el orden de los argumentos no corrige una asignación duplicada a un parámetro.

Reconoce las palabras clave en las funciones incorporadas

print("a", "b", "c", sep="-")
print("Loading", end="...")
print("done")

La primera línea muestra «a-b-c». sep proporciona el texto situado entre los valores mostrados. Las dos llamadas siguientes producen «Loading...done» en una línea: end sustituye el salto de línea habitual después de «Loading».

Algunas funciones incorporadas también aceptan argumentos por nombre; por ejemplo, round(3.14159, ndigits=2) da 3,14. Usa los nombres de parámetros documentados para la función que llamas. Una palabra descriptiva que inventes no se reconoce solo porque parezca adecuada para la tarea.

Un valor predeterminado permite que una llamada omita un argumento cuando una elección habitual resulta adecuada. Escribe el valor predeterminado junto a su parámetro en la cabecera. Proporcionar un argumento sustituye el valor predeterminado para esa llamada.

Haz que un parámetro sea opcional

def greet(name, greeting="Hello"):
    print(greeting + ",", name + "!")

greet("Ana")
greet("Ana", "Welcome")
greet("Ana", greeting="Hi")

La salida es «Hello, Ana!», «Welcome, Ana!» y «Hi, Ana!». name es obligatorio porque no tiene un valor predeterminado. Por tanto, greet() lanza un TypeError, aunque el otro parámetro sea opcional.

En estas cabeceras, los parámetros obligatorios van antes de los que tienen valores predeterminados. def greet(greeting="Hello", name): no es válido. Python informa de un error de sintaxis porque un parámetro sin valor predeterminado aparece después de uno que sí lo tiene. Mueve name antes de greeting para mantenerlo como obligatorio.

Cambia una opción

def order_coffee(size, shots=1, milk="none"):
    print(size, "coffee,", shots, "shot(s), milk:", milk)

order_coffee("large", milk="oat")

Esto muestra «large coffee, 1 shot(s), milk: oat». La palabra clave llega a milk mientras shots conserva 1. Una llamada posicional como order_coffee("medium", 2) modifica shots y deja milk en «none». La asociación posicional no se salta un parámetro opcional para llegar al siguiente.

Las funciones incorporadas también ofrecen valores predeterminados: una llamada normal a print() separa los valores con un espacio y termina con un salto de línea. round(3.7) da el número entero 4; round(3.14159, 2) solicita dos decimales y da 3,14.

Los valores predeterminados se crean al ejecutar la definición

rate = 0.05

def price_with_tax(price, tax_rate=rate):
    return price * (1 + tax_rate)

rate = 0.08
print(price_with_tax(100))
print(price_with_tax(100, rate))

El valor predeterminado guarda 0,05 cuando se ejecuta def. Cambiar rate después no modifica ese valor guardado. Las llamadas muestran «105.0» y «108.0»: solo la segunda proporciona explícitamente la nueva tasa.

Evita compartir una lista por accidente

Una lista contiene elementos, y append añade un elemento a esa misma lista. Con una lista como valor predeterminado, todas las llamadas que omiten el argumento la comparten:

def add_item(item, basket=[]):
    basket.append(item)
    print(basket)

add_item("apple")
add_item("pear")

Esto muestra ['apple'] y después ['apple', 'pear']. La lista predeterminada se creó una vez, no una vez por llamada. Para crear una lista nueva cada vez que se omita el argumento, usa None como señal:

def add_item(item, basket=None):
    if basket is None:
        basket = []
    basket.append(item)
    print(basket)

Ahora esas dos llamadas muestran ['apple'] y ['pear']. Una lista proporcionada explícitamente sigue usándose tal como se recibe. Describe los parámetros opcionales y sus valores predeterminados en la cadena de documentación para que quienes llamen a la función sepan qué valores se eligen al omitirlos.

Una función puede dar al código que la llama un resultado que pueda usar. La sentencia return termina la llamada y devuelve su valor. En el punto de llamada, la llamada representa ese valor devuelto.

Guarda y combina resultados

def rectangle_area(width, height):
    return width * height

area = rectangle_area(4, 2.5)
print(area)
print(rectangle_area(3, 4) + rectangle_area(2, 5))

La primera llamada devuelve 10,0, que se asigna a area; el primer print lo muestra. En la última línea, las dos llamadas devuelven 12 y 10. Python suma esos resultados y muestra «22». La propia función no contiene ningún print, así que puede proporcionar tanto un resultado que se guarde como una parte de un cálculo mayor.

Un valor devuelto también puede comprobarse en una condición o pasarse a otra función. Esto separa la tarea de calcular de la decisión del código que realiza la llamada sobre cómo usar la respuesta.

Mostrar y devolver tienen tareas distintas

def double_print(n):
    print(n * 2)

result = double_print(5)
print(result)

La llamada muestra «10», pero ese número mostrado no se devuelve como resultado. double_print llega al final de su cuerpo, así que devuelve None. Por eso la última línea muestra «None».

double_print(5) + 1 primero muestra «10» y después lanza TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'. Sustituye el cuerpo por return n * 2 cuando el código que realiza la llamada necesite el doble del número. Una función destinada solo a producir un efecto, como mostrar un mensaje, puede devolver None de forma adecuada; estas funciones se denominan a veces funciones sin valor de retorno útil. Una función que devuelve un resultado útil se denomina a veces función con valor de retorno útil.

Detente en el primer return ejecutado

def to_fahrenheit(celsius):
    return celsius * 9 / 5 + 32
    print("Converted")

print(to_fahrenheit(20))

Esto muestra «68.0». Nunca se llega al print del cuerpo porque return ya ha terminado la llamada. Elimina esa sentencia inalcanzable o mueve una acción necesaria antes del retorno. La conversión devuelve números de coma flotante porque / produce un número de coma flotante. Las entradas 100 y -40 dan 212,0 y -40,0.

Un return sin expresión también termina una llamada y devuelve None. Toda llamada a función tiene un resultado, aunque no se haya proporcionado un valor útil.

Haz visibles los resultados en un archivo de programa

Una llamada aislada a rectangle_area(3, 4) calcula 12 y después descarta el resultado sin usar en un archivo. Usa print(rectangle_area(3, 4)) para mostrarlo o asígnalo a una variable. La consola interactiva muestra los resultados de las expresiones salvo None, así que una prueba correcta en la consola puede parecer distinta de ejecutar la misma línea en un archivo.

Distintas entradas pueden necesitar distintas respuestas. Una función puede tener varias sentencias return, pero una llamada se detiene en la primera que ejecuta. Sigue la ruta real a través de sus ramas y bucles para encontrar el resultado.

Ordena las comprobaciones que se solapan

def letter_grade(score):
    if score >= 90:
        return "A"
    if score >= 80:
        return "B"
    if score >= 70:
        return "C"
    return "F"

Para 85, la primera condición es falsa y la segunda es verdadera. La función devuelve «B» sin comprobar las condiciones restantes. Para 42, las tres condiciones son falsas, así que el return final proporciona «F». Las sentencias if independientes funcionan porque cada rama cuya condición se cumple termina la llamada.

Aquí debe comprobarse primero el umbral más alto. Si score >= 70 fuera primero, una puntuación de 95 devolvería «C». Con rangos que se solapan, una coincidencia amplia al principio puede ocultar una respuesta posterior más específica.

Cubre la ruta sin ninguna rama coincidente

def sign(n):
    if n > 0:
        return "positive"
    elif n < 0:
        return "negative"
    return "zero"

La última línea cubre el cero. Sin ella, sign(0) llegaría al final y devolvería None. Sigue una entrada de cada rama y de cualquier caso restante; probar solo entradas positivas y negativas no detectaría este vacío.

Devuelve una comparación booleana

def is_even(n):
    return n % 2 == 0

if is_even(10):
    print("Even")

La comparación ya produce True o False. is_even(10) devuelve True, mientras que is_even(7) devuelve False. Usa el resultado directamente en una condición. Añadir == True no mejora la comprobación.

Termina la búsqueda antes de informar de que no hay coincidencias

def smallest_divisor(n):
    for d in range(2, n):
        if n % d == 0:
            return d
    return n

Para 91, los candidatos del 2 al 6 fallan y después el 7 lo divide exactamente. Devolver 7 termina tanto el bucle como la función. Para 13, el bucle no encuentra ningún divisor, así que el return final da 13.

Una prueba de primalidad debe permitir que la búsqueda continúe después de un candidato que no sirve:

def is_prime(n):
    if n < 2:
        return False
    for d in range(2, n):
        if n % d == 0:
            return False
    return True

El True final está fuera del bucle. Colocarlo en un else dentro del bucle devolvería un valor después de comprobar solo el primer candidato: el 9 se aceptaría erróneamente porque no es divisible por 2. Con la función corregida, 9 y 1 devuelven False; 2, 7 y 97 devuelven True. Para 2, el bucle no tiene candidatos y la ejecución llega al True final.

Devuelve dos valores

def share(total, people):
    return total // people, total % people

each, left = share(17, 5)
print(each, left)

La llamada devuelve una tupla, un resultado agrupado que contiene 3 y 2. La asignación lo desempaqueta en dos nombres, así que la salida es «3 2». Mostrar la llamada directamente produciría «(3, 2)». El número de nombres debe coincidir con el número de valores que se desempaquetan.

Combina llamadas de dentro hacia fuera

def add(a, b):
    return a + b

def to_fahrenheit(celsius):
    return celsius * 9 / 5 + 32

print(to_fahrenheit(add(10, 15)))

add devuelve primero 25. Ese valor se convierte en el argumento de to_fahrenheit, que devuelve 77,0. Por último, print muestra «77.0». Cada llamada interna debe devolver el valor que necesita la siguiente función.

El ámbito describe dónde puede usarse un nombre. Los parámetros y los nombres a los que se asignan valores dentro de una función son locales a la llamada de esa función. El código que realiza la llamada y una función pueden usar nombres similares sin compartir las mismas variables locales.

Mantén los nombres locales dentro de su llamada

def make_greeting():
    message = "Hi"
    print(message)

make_greeting()

Esto muestra «Hi». Añadir print(message) después de la llamada lanza NameError: name 'message' is not defined: el nombre local no está disponible allí. Para poner el valor a disposición del código que realiza la llamada, devuélvelo y guárdalo:

def make_greeting():
    return "Hi"

message = make_greeting()
print(message)

El message del nivel superior es una variable nueva del código que realiza la llamada y recibe el valor devuelto. La función no hace visibles fuera sus propios nombres locales.

Cada llamada recibe variables locales nuevas. Si un cuerpo establece count = 0, suma 1 y lo muestra, dos llamadas muestran «1» y «1». La segunda no continúa con el contador de la primera. Distintas funciones también pueden usar nombres locales como total de forma independiente.

Sigue la ocultación y la búsqueda de nombres

x = 10

def show():
    x = 5
    print(x)

show()
print(x)

La salida es «5» y después «10». La x local oculta la x global dentro de show; la asignación no modifica el valor del nivel superior. Una variable global pertenece al ámbito del nivel superior del archivo. Las asignaciones ordinarias fuera de las funciones crean variables globales.

Para una función definida en el nivel superior del archivo, Python busca un nombre entre sus nombres locales, después entre los globales del archivo y, por último, entre los incorporados, como print. Se usa la primera coincidencia. Por tanto, los nombres locales y globales son lugares distintos que revisar cuando un valor parece incorrecto.

Reasignar un parámetro no modifica el nombre del código que realiza la llamada

def add_bonus(points):
    points = points + 10
    print(points)

score = 50
add_bonus(score)
print(score)

points empieza con el valor 50. Su reasignación local lo convierte en 60, así que la primera salida es «60». El score del código que realiza la llamada sigue valiendo 50. Para actualizar ese nombre explícitamente, usa una función que devuelva points + 10 y después escribe score = add_bonus(score).

Modificar una lista es una operación distinta

Una lista puede compartirse mediante dos nombres:

def add_guest(guests, name):
    guests.append(name)

party = ["Ana"]
add_guest(party, "Ben")
print(party)

El parámetro guests y la variable party del código que realiza la llamada hacen referencia a la misma lista. append modifica su contenido, así que la salida es «['Ana', 'Ben']». En cambio, asignar guests = [] dentro de la función haría que solo el nombre local apuntara a una lista nueva; party seguiría haciendo referencia a la original. Al seguir un argumento de tipo lista, pregúntate si la línea modifica el objeto compartido o solo reasigna un nombre local.

Una función puede leer un nombre global sin una declaración. Asignar un valor a un nombre en su cuerpo sigue una regla distinta, y confundir estas operaciones es una causa habitual de UnboundLocalError.

Lee un ajuste fijo

TAX_RATE = 0.25

def tax(amount):
    return amount * TAX_RATE

print(tax(80))

La salida es «20.0». amount es local; TAX_RATE se lee de las variables globales del archivo. Las mayúsculas identifican una constante por convención e indican que el programa debe mantener fijo el ajuste. Python no impone esa convención.

La asignación convierte un nombre en local en todo el cuerpo

total = 0

def add_to_total(amount):
    total = total + amount

add_to_total(5)

La asignación convierte total en local en toda add_to_total. Para calcular el lado derecho, Python intenta leer ese nombre local antes de que tenga un valor. No recurre al total global. La llamada lanza UnboundLocalError: cannot access local variable 'total' where it is not associated with a value.

La decisión se basa en todo el cuerpo, no solo en las líneas ya ejecutadas. Un cuerpo con print(count) seguido de count = 10 también trata count como local en la línea que lo muestra. Un count global no puede proporcionar el valor local que falta.

Declara una asignación global deliberada

total = 0

def add_to_total(amount):
    global total
    total = total + amount

add_to_total(5)
add_to_total(7)
print(total)

Ahora tanto la lectura como la asignación hacen referencia al nombre global, así que la salida es «12». Coloca global total antes de cualquier uso de total en la función. Usar el nombre antes de su declaración es un error de sintaxis.

Una declaración por sí sola no crea un valor. Una asignación posterior puede crear una variable global que no existía: el cuerpo de una función que contenga global level y después level = 1 crea el level global cuando se llama a la función.

Muestra el cambio mediante entradas y un resultado

La misma suma acumulada puede escribirse con una interfaz explícita:

def add_to_total(total, amount):
    return total + amount

total = 0
total = add_to_total(total, 5)
total = add_to_total(total, 7)
print(total)

Esto también muestra «12». Cada llamada muestra el valor anterior que se pasa, y la asignación muestra adónde va el nuevo. Puedes comprobar add_to_total(10, 3) por separado sin preparar antes un estado global oculto. Si varias funciones modifican la misma variable global, su comportamiento depende del orden en que se ejecutan.

Leer una lista compartida y modificar su contenido usa la referencia existente. Sustituir el valor de ese nombre global por una lista distinta es una asignación, así que se aplica la regla de asignación.

Quien llama a una función necesita conocer su tarea sin leer toda su implementación. Una cadena de documentación proporciona esa descripción. Python reconoce una cadena como la cadena de documentación de la función cuando es la primera sentencia del cuerpo.

Escribe primero una descripción breve

def to_fahrenheit(celsius):
    """Convert a temperature from degrees Celsius to degrees Fahrenheit."""
    return celsius * 9 / 5 + 32

print(to_fahrenheit.__doc__)

La salida es la frase que está entre las comillas. Python guarda la cadena de documentación en __doc__; las comillas triples no forman parte de la frase guardada. help(to_fahrenheit) muestra la descripción junto con la firma to_fahrenheit(celsius). Pasa el nombre de la función a help, sin llamar a la función.

La convención habitual es usar comillas dobles triples, incluso para una cadena de documentación de una línea. Empieza con una orden como «Devuelve el área de un rectángulo.» y termina con un punto. Mantén una descripción breve y sus comillas de cierre en una sola línea. No necesitas repetir el nombre de la función ni la lista de parámetros porque la ayuda ya los incluye.

Añade detalles cuando sean necesarios para llamar a la función

def split_bill(total, people, tip_rate=0.2):
    """Return each person's share of a bill, including the tip.

    total: the bill before the tip
    people: the number of people sharing the bill
    tip_rate: the tip as a fraction of the bill (default 0.2)
    """
    return total * (1 + tip_rate) / people

La primera línea indica el resultado. Una línea en blanco la separa de los detalles sobre las entradas. El valor predeterminado se documenta como 0,2, una fracción de la cuenta; esto evita que quien llama a la función use 20 como valor para una propina del 20 %. Las comillas de cierre de una cadena de documentación de varias líneas van en una línea aparte.

Para split_bill(84, 4), la función aplica la propina predeterminada y devuelve 25,2. Quien la llama puede conocer el significado de las tres entradas antes de elegir los argumentos. Incluye las unidades cuando sean relevantes y describe efectos como mostrar algo, para que se puedan predecir tanto el resultado como el comportamiento visible.

Distingue la documentación de los comentarios

Una cadena situada después de una asignación u otra sentencia del cuerpo no es la cadena de documentación de la función. Es una expresión de cadena sin usar, y __doc__ es None si no hay una cadena de documentación como primera sentencia. Un comentario con # tampoco se convierte en la descripción de la ayuda.

Escribe el resumen mientras decides la tarea de la función. Si la frase necesita varias acciones sin relación entre sí, reconsidera si conviene dividir la función. Cuando cambies parámetros, valores predeterminados, valores devueltos o efectos en pantalla, actualiza la cadena de documentación al mismo tiempo; quienes llaman a la función confían en ella como parte de la interfaz.

La descomposición consiste en dividir una tarea en tareas más pequeñas. Cada función se responsabiliza de una tarea, con entradas claras y un resultado o efecto claro. Así, el programa principal puede leerse como una secuencia breve de pasos con nombre.

Planifica los datos antes de escribir los cuerpos

Para un programa que informa de la media de unas puntuaciones de pruebas y de una calificación con letra, identifica tres tipos de trabajo: leer puntuaciones, calcular una media y elegir una calificación. Decide qué recibe y devuelve cada función auxiliar. Deja la salida en pantalla en main, donde se reúnen los resultados.

def get_score(prompt):
    return float(input(prompt))

def average(a, b, c):
    return (a + b + c) / 3

def letter_grade(score):
    if score >= 90:
        return "A"
    if score >= 80:
        return "B"
    if score >= 70:
        return "C"
    return "F"

def main():
    first = get_score("Test 1: ")
    second = get_score("Test 2: ")
    third = get_score("Test 3: ")
    avg = average(first, second, third)
    print("Average:", round(avg, 1), "Grade:", letter_grade(avg))

main()

Con las puntuaciones 78, 92 y 85, average devuelve 85,0. Ese resultado se convierte en el argumento de letter_grade, que devuelve «B». La salida en pantalla es «Average: 85.0 Grade: B».

main coordina la secuencia; no necesita saber cómo elige letter_grade su respuesta. Usar una función mediante su tarea e interfaz, sin seguir cada sentencia de su cuerpo, es abstracción procedimental. Ya usas print de esta forma.

Ofrece una interfaz clara al código que realiza la llamada

La interfaz de una función consta de su nombre, sus parámetros, el resultado devuelto y su comportamiento documentado. average(a, b, c) necesita tres números y devuelve su media. El código que la llama no tiene que leer una solicitud de datos ni capturar texto mostrado para obtener ese número. Puedes reescribir el cálculo manteniendo las entradas y la salida acordadas, y las llamadas existentes seguirán funcionando.

Usa nombres como calculate_total y print_receipt para acciones, e is_even o has_discount para preguntas booleanas. Los nombres de parámetros como price y quantity explican qué valores corresponden a cada posición. Los nombres de una sola letra pueden ser adecuados cuando su significado está claro, como en las tres entradas de average.

Convierte la repetición en parámetros

Si varias partes de un programa muestran títulos distintos entre las mismas líneas de signos igual, convierte el título en un parámetro de print_heading(title). La estructura repetida pertenece a un solo cuerpo, mientras que el texto variable pertenece a las llamadas. Así, un cambio posterior en la longitud de la línea solo necesita una modificación.

Elige cómo dividir las funciones para que las tareas sean más fáciles de entender o reutilizar. Colocar todas las sentencias en una única main larga oculta las tareas más pequeñas. Convertir cada expresión trivial en una función auxiliar usada una sola vez puede añadir nombres sin mejorar la legibilidad. Una comprobación útil es ver si una frase breve puede describir cada tarea y sus entradas y salidas.

Termina el archivo con la llamada real a main() después de todas las definiciones. Un programa que solo contiene definiciones creará sus funciones y terminará sin ejecutar sus cuerpos.

Crear varias funciones antes de ejecutar alguna dificulta localizar un fallo. El desarrollo incremental consiste en escribir una parte pequeña, comprobarla y después añadir la siguiente. Mantienes un programa que funciona y reduces la cantidad de código nuevo que debes revisar.

Usa un esbozo de función durante la planificación

Un esbozo de función tiene la cabecera prevista y un cuerpo provisional. Una cadena de documentación y pass mantienen válida la definición, pero la función devuelve None hasta que la implementes. Un retorno fijo puede ayudar a probar la salida en pantalla del código que la llama sin dar por hecho que el cálculo real ya funciona.

Empieza con una función auxiliar de cálculo cuyo resultado puedas obtener de forma independiente. Una vez que se comporte correctamente, conéctala con la siguiente. Deja la entrada interactiva para cuando los cálculos puedan comprobarse con llamadas directas.

Decide los resultados esperados antes de ejecutar

Con las funciones average y letter_grade, las puntuaciones 70, 75 y 72 tienen una media aproximada de 72,33, así que su calificación esperada es «C». Comprueba ambas etapas:

print(average(70, 75, 72))
print(letter_grade(average(70, 75, 72)) == "C")

Las salidas son «72.33333333333333» y «True». La comparación comprueba directamente la calificación esperada; mirar solo la salida del propio programa sin una expectativa independiente puede hacer que una respuesta errónea pero plausible pase inadvertida.

Prueba los límites además de las entradas habituales

Para un umbral de 90, prueba 90 y 89,9. La función de calificación correcta devuelve «A» y «B». Si su primera condición fuera score > 90, solo la comprobación del límite exacto revelaría que 90 pasa erróneamente a la siguiente condición.

Incluye un valor habitual, límites exactos, valores cercanos y entradas extremas que la función deba gestionar. En la función de calificación, comprobar 70 y 0 recorre el límite mínimo para aprobar y la ruta final de «F». Una comprobación como print(letter_grade(85) == "B") es sencilla porque la función recibe un valor y devuelve su resultado.

Lee la traza de la excepción y revisa el valor recibido

Supón que main llama a letter_grade(input("Score: ")). Introducir «85» envía una cadena a una comparación con un número. El error final es TypeError: '>=' not supported between instances of 'str' and 'int'. La traza señala la comparación dentro de la función auxiliar, mientras que una línea de llamada anterior señala main.

El fallo se produce en la comparación, pero la corrección corresponde al lugar donde se prepara la entrada: conviértela con float() antes de pasarla. Un print("letter_grade got", score) temporal como primera línea ayuda a revelar una entrada inesperada. Si su tipo no está claro, revisa el código que realiza la llamada y la conversión que usa. Elimina las salidas de depuración después de corregir el error.

Relaciona los síntomas con las causas probables

Después de corregir una función auxiliar, vuelve a ejecutar las comprobaciones que recorran las rutas afectadas y el código que la llama para conectarla con el programa.