Funções em Python

Uma função é um bloco de código com nome que realiza uma tarefa. Funções embutidas como print() e input() já oferecem tarefas úteis que você pode chamar; def permite criar suas próprias funções. Um bom nome transforma várias linhas de trabalho em uma chamada que indica o que você quer que seja feito.

Escreva o cabeçalho e o corpo

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

greet()
greet()

O cabeçalho começa com def, seguido do nome, dos parênteses e de dois-pontos. As linhas indentadas formam o corpo. Use quatro espaços para cada nível de indentação. As linhas greet() sem indentação estão fora da função, portanto são chamadas no programa principal.

Quando Python chega à definição, ele cria a função e lhe dá o nome greet. Ele ainda não imprime nenhuma das mensagens. A primeira chamada começa na primeira linha do corpo e imprime “Hello!”, seguido de “Welcome to Python.”. A segunda chamada começa o corpo novamente e imprime as mesmas duas linhas. Há quatro linhas de saída ao todo.

Um nome e uma chamada são diferentes

Os parênteses em greet() fazem dela uma chamada, embora essa função não precise de entradas. Uma linha que contém apenas greet faz referência à função e não executa nada. print(greet) exibe uma descrição do objeto de função, incluindo um endereço de memória; ele não executa a saudação.

Python precisa ter executado uma definição antes que uma chamada use seu nome. Se um arquivo começa com greet() e define greet depois, a primeira linha gera NameError: name 'greet' is not defined. Coloque a definição acima da chamada no nível superior.

Escolha nomes que expliquem a tarefa

Use palavras em minúsculas unidas por sublinhados, como print_receipt ou convert_to_miles. Nomes podem conter letras, dígitos e sublinhados, mas não podem começar com um dígito nem ser uma palavra reservada como return. Os nomes distinguem maiúsculas de minúsculas: greet e Greet são nomes diferentes.

Mantenha os nomes embutidos disponíveis. Depois de input = "yes", o nome input se refere a texto, então input("Name? ") gera TypeError: 'str' object is not callable. Dar à variável o nome answer mantém a função embutida acessível.

Corrija primeiro a estrutura

A falta de dois-pontos no cabeçalho produz SyntaxError: expected ':'. Um corpo vazio ou sem indentação produz um IndentationError. Uma função planejada ainda precisa de uma instrução; pass é uma instrução provisória que não faz nada:

def print_receipt():
    pass

print_receipt()

Esse programa é executado sem saída. A chamada chega a pass e depois ao fim do corpo. Substitua a instrução provisória pela tarefa real quando estiver pronto para implementá-la. Se uma linha deveria pertencer ao corpo, mas é executada no momento errado, verifique sua indentação antes de alterar a chamada.

Um programa com funções não executa todos os corpos na ordem em que aparecem na página. Uma chamada altera o fluxo de execução: Python entra na função chamada, termina seu trabalho e retoma o código chamador logo após essa chamada.

Acompanhe uma chamada dentro de outra

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

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

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

Primeiro, Python define line e banner. Nenhum dos corpos é executado. A próxima instrução imprime “Start”. A chamada a banner() entra em seu corpo, cuja primeira instrução chama line().

Python agora entra em line, imprime “----------” e chega ao fim. Ele retorna à próxima instrução em banner, que imprime “ REPORT”. A segunda chamada a line() imprime outra linha de traços. Por fim, banner termina, então o programa principal continua e imprime “End”.

A saída é:

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

Acompanhe as chamadas não concluídas

Enquanto line é executada, banner espera que ela termine. O programa principal também espera por banner. Python registra essas chamadas não concluídas na pilha de chamadas. A chamada ativa mais interna termina primeiro, e cada código chamador continua em sua própria próxima instrução.

Para um rastreamento no papel, numere as linhas do programa. Registre uma linha do corpo apenas quando a execução chegar a ela por meio de uma chamada. Em cada chamada, marque onde a execução será retomada. Escreva a saída quando seu print for executado, mantendo os espaços e as quebras de linha. Isso separa o caminho pelo código da saída que ele produz.

Defina funções auxiliares antes de serem necessárias

A definição da função auxiliar pode aparecer abaixo da definição da função que a chama:

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

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

show_report()

Isso funciona porque ambas as definições foram executadas antes de a chamada final entrar em show_report. Python procura draw_line quando o corpo efetivamente a chama. Mover show_report() para cima de def draw_line(): faria a chamada falhar ao tentar usar a função auxiliar ausente.

Chamadas repetidas começam do início

Uma chamada dentro de um laço entra no corpo a cada repetição:

for i in range(3):
    line()

Usando a primeira definição de line, isso imprime a linha de traços três vezes. A função começa na primeira instrução de seu corpo a cada chamada.

Se uma chamada falhar, Python mostra um traceback. Sua última linha apresenta o tipo de erro e a mensagem. As entradas de chamadas acima dela vão da chamada não concluída mais externa até a linha que falhou. Ler primeiro o erro final e depois verificar a linha mais interna e o código que a chamou ajuda a localizar tanto a operação que falhou quanto o caminho que forneceu seus dados.

Uma função se torna reutilizável com entradas diferentes quando seu cabeçalho nomeia os valores de que ela precisa. Esses nomes são parâmetros. O código chamador fornece argumentos, que são os valores efetivamente usados em uma chamada específica.

Associe valores a nomes

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

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

Os parâmetros são width e height. Na primeira chamada, os argumentos são 4 e 2.5. Argumentos posicionais são associados da esquerda para a direita: width recebe 4 e height recebe 2,5. O corpo imprime “Area: 10.0”. A próxima chamada fornece novos valores aos mesmos nomes de parâmetros e imprime “Area: 21”.

Cada parâmetro funciona como uma variável dentro daquela chamada. Você não precisa atribuir valores a width e height antecipadamente; a chamada os fornece. Uma função sem parâmetros ainda precisa de parênteses vazios tanto na definição quanto nas chamadas.

A ordem pode mudar o significado

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

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

A primeira chamada imprime “Milo is a cat”. A segunda imprime “cat is a Milo”. Ambas as chamadas são válidas em Python, então nenhum erro sinaliza a troca de significado. Leia a ordem do cabeçalho antes de escolher argumentos posicionais, especialmente quando vários parâmetros aceitam o mesmo tipo de valor.

Argumentos podem ser expressões

Python avalia cada expressão de argumento antes de o corpo começar. Com side = 6, a chamada rectangle_area(side, side) passa 6 duas vezes e imprime “Area: 36”. O nome da variável do código chamador não precisa corresponder a nenhum dos nomes dos parâmetros. A chamada rectangle_area(side + 1, 2) passa 7 e 2; ela não passa o texto “side + 1”.

Leia um erro de quantidade de argumentos

Todo parâmetro sem valor padrão precisa de um argumento. Com a função de área acima:

A primeira gera TypeError: rectangle_area() missing 1 required positional argument: 'height'. A segunda gera TypeError: rectangle_area() takes 2 positional arguments but 3 were given. Verifique o cabeçalho da função indicada e depois conte como a chamada preenche seus parâmetros.

Passe o tipo de valor necessário para a tarefa

Python não impõe um tipo simplesmente porque um parâmetro se chama width. rectangle_area("4", 2) imprime “Area: 44”, pois multiplicar um texto por um inteiro repete esse texto. Como input() retorna texto, converta a entrada numérica antes de passá-la:

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

Aqui float() transforma o texto digitado em um número antes que a função de área o receba.

Um argumento nomeado identifica seu parâmetro de destino na chamada. Isso facilita a leitura quando vários valores podem ser confundidos. Python associa o nome ao do cabeçalho, em vez de usar sua posição.

Associe pelo nome

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

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

Ambas as chamadas imprimem “Milo is a cat”. A ordem dos argumentos nomeados pode mudar porque cada valor identifica o parâmetro que preenche. A mesma ideia torna rectangle_area(width=4, height=2.5) compreensível sem verificar qual dimensão veio primeiro.

Um nome de argumento não é uma nova variável no código chamador. Em describe_pet(name="Milo", animal="cat"), name= direciona “Milo” ao parâmetro. Ele não atribui “Milo” a uma variável de nível superior chamada name. Escreva argumentos nomeados sem espaços em torno de =, seguindo o estilo usual do Python.

Combine argumentos posicionais e nomeados

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

O primeiro argumento preenche animal por posição. O argumento nomeado preenche name, então cada parâmetro recebe exatamente um valor. Argumentos posicionais devem vir primeiro. A chamada describe_pet(name="Milo", "cat") é rejeitada com SyntaxError: positional argument follows keyword argument.

Para examinar uma chamada mista, preencha as posições dos argumentos posicionais da esquerda para a direita e depois associe os argumentos nomeados. Verifique se nenhuma posição foi preenchida duas vezes e se nenhum parâmetro obrigatório ficou vazio.

Corrija argumentos nomeados duplicados ou desconhecidos

A duplicação gera TypeError: describe_pet() got multiple values for argument 'animal'. O erro de digitação gera TypeError: describe_pet() got an unexpected keyword argument 'nmae'. Compare os nomes caractere por caractere; letras maiúsculas e minúsculas também importam. Mudar a ordem dos argumentos não corrige uma atribuição duplicada a um parâmetro.

Reconheça argumentos nomeados em funções embutidas

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

A primeira linha imprime “a-b-c”. sep fornece o texto entre os valores exibidos. As duas chamadas seguintes produzem “Loading...done” em uma linha: end substitui a habitual nova linha após “Loading”.

Algumas funções embutidas também aceitam argumentos nomeados; por exemplo, round(3.14159, ndigits=2) produz 3,14. Use os nomes de parâmetros documentados para a função que você está chamando. Uma palavra descritiva inventada por você não é reconhecida apenas porque parece adequada à tarefa.

Um valor padrão permite que uma chamada omita um argumento quando uma escolha comum é adequada. Escreva o valor padrão ao lado do parâmetro no cabeçalho. Fornecer um argumento substitui o valor padrão naquela chamada.

Torne um parâmetro opcional

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

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

A saída é “Hello, Ana!”, “Welcome, Ana!” e “Hi, Ana!”. name é obrigatório porque não tem valor padrão. Portanto, greet() gera um TypeError, embora o outro parâmetro seja opcional.

Nesses cabeçalhos, parâmetros obrigatórios vêm antes dos parâmetros com valores padrão. def greet(greeting="Hello", name): é inválido. Python informa um erro de sintaxe sobre um parâmetro sem valor padrão que vem depois de um com valor padrão. Mova name para antes de greeting para mantê-lo obrigatório.

Altere uma opção

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

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

Isso imprime “large coffee, 1 shot(s), milk: oat”. O argumento nomeado chega a milk enquanto shots mantém 1. Uma chamada posicional order_coffee("medium", 2) altera shots e deixa milk em “none”. A associação posicional não pula um parâmetro opcional para chegar ao próximo.

Funções embutidas também oferecem valores padrão: um print() comum separa valores com um espaço e termina com uma nova linha. round(3.7) produz o número inteiro 4; round(3.14159, 2) solicita duas casas decimais e produz 3,14.

Valores padrão são criados quando a definição é executada

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))

O valor padrão armazena o valor 0,05 quando def é executado. Alterar rate depois não altera esse valor padrão armazenado. As chamadas imprimem “105.0” e “108.0”: apenas a segunda fornece explicitamente a nova taxa.

Evite compartilhar uma lista por acidente

Uma lista contém itens, e append adiciona um item a essa mesma lista. Com uma lista como valor padrão, todas as chamadas que omitem o argumento a compartilham:

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

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

Isso imprime ['apple'] e depois ['apple', 'pear']. A lista padrão foi criada uma vez, não uma vez por chamada. Para criar uma lista nova para cada argumento omitido, use None como sinal:

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

Agora essas duas chamadas imprimem ['apple'] e ['pear']. Uma lista fornecida explicitamente continua sendo usada como foi passada. Descreva os parâmetros opcionais e seus valores padrão na docstring para que o código chamador saiba quais valores são escolhidos quando eles são omitidos.

Uma função pode fornecer ao código chamador um resultado para usar. A instrução return encerra a chamada e devolve seu valor. No ponto da chamada, ela passa a representar o valor retornado.

Armazene e combine 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))

A primeira chamada retorna 10,0, que é atribuído a area; o primeiro print o exibe. Na última linha, as duas chamadas retornam 12 e 10. Python soma esses resultados e imprime “22”. A própria função não contém print, então pode fornecer tanto um resultado armazenado quanto parte de um cálculo maior.

Um valor retornado também pode ser testado em uma condição ou passado para outra função. Isso separa a tarefa de calcular da decisão do código chamador sobre como usar a resposta.

Imprimir e retornar têm tarefas diferentes

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

result = double_print(5)
print(result)

A chamada exibe “10”, mas esse número exibido não é devolvido como resultado. double_print chega ao fim de seu corpo, então retorna None. Portanto, a última linha imprime “None”.

double_print(5) + 1 primeiro imprime “10” e depois gera TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'. Substitua o corpo por return n * 2 quando o código chamador precisar do número dobrado. Uma função destinada apenas a produzir um efeito, como exibir uma mensagem, pode retornar None; essas funções são às vezes chamadas de funções sem retorno útil. Uma função com um resultado retornado útil é às vezes chamada de função com retorno útil.

Pare no primeiro return executado

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

print(to_fahrenheit(20))

Isso imprime “68.0”. O print dentro do corpo nunca é alcançado porque return já encerrou a chamada. Remova essa instrução inalcançável ou mova uma ação necessária para antes do return. A conversão retorna números de ponto flutuante porque / produz um número desse tipo. As entradas 100 e -40 produzem 212,0 e -40,0.

Um return sem expressão também encerra uma chamada, retornando None. Toda chamada de função tem um resultado, mesmo quando nenhum valor útil foi fornecido.

Torne os resultados visíveis em um arquivo de programa

Um rectangle_area(3, 4) sozinho calcula 12 e depois descarta o resultado não utilizado em um arquivo. Use print(rectangle_area(3, 4)) para exibi-lo ou atribua-o a uma variável. O interpretador interativo exibe resultados de expressões, exceto None, então um teste bem-sucedido no interpretador pode parecer diferente da execução da mesma linha em um arquivo.

Entradas diferentes podem precisar de respostas diferentes. Uma função pode ter várias instruções return, mas uma chamada para na primeira que executa. Siga o caminho efetivo por seus ramos e laços para encontrar o resultado.

Ordene testes que se sobrepõem

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

Para 85, o primeiro teste é falso e o segundo é verdadeiro. A função retorna “B” sem testar as condições restantes. Para 42, os três testes são falsos, então o return final fornece “F”. Instruções if separadas funcionam porque cada ramo que corresponde encerra a chamada.

O maior valor limiar deve ser verificado primeiro aqui. Se score >= 70 viesse primeiro, uma pontuação de 95 retornaria “C”. Com intervalos sobrepostos, uma correspondência ampla e antecipada pode ocultar uma resposta posterior mais específica.

Cubra o caminho sem ramo correspondente

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

A última linha trata o zero. Sem ela, sign(0) chegaria ao fim e retornaria None. Rastreie uma entrada de cada ramo e qualquer caso restante; testar apenas entradas positivas e negativas deixaria essa lacuna passar despercebida.

Retorne uma comparação booleana

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

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

A comparação já produz True ou False. is_even(10) retorna True, enquanto is_even(7) retorna False. Use o resultado diretamente em uma condição. Um == True adicional não ajuda no teste.

Termine uma busca antes de informar que não houve correspondência

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

Para 91, os candidatos de 2 a 6 falham, então 7 o divide exatamente. Retornar 7 encerra tanto o laço quanto a função. Para 13, o laço não encontra nenhum divisor, então o return final fornece 13.

Um teste de primalidade precisa permitir que a busca continue após um candidato falhar:

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

O True final está fora do laço. Colocá-lo em um else dentro do laço faria a função retornar depois de verificar apenas o primeiro candidato: 9 seria aceito incorretamente porque não é divisível por 2. Com a função corrigida, 9 e 1 retornam False; 2, 7 e 97 retornam True. Para 2, o laço não tem candidatos e a execução chega ao True final.

Devolva dois valores

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

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

A chamada retorna uma tupla, um resultado agrupado que contém 3 e 2. A atribuição a desempacota em dois nomes, então a saída é “3 2”. Imprimir a chamada diretamente mostraria “(3, 2)”. O número de nomes deve corresponder ao número de valores desempacotados.

Combine chamadas de dentro para fora

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

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

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

add primeiro retorna 25. Esse valor se torna o argumento de to_fahrenheit, que retorna 77,0. Por fim, print exibe “77.0”. Cada chamada interna deve retornar o valor de que a próxima função precisa.

Escopo descreve onde um nome pode ser usado. Parâmetros e nomes aos quais se atribuem valores dentro de uma função são locais à chamada dessa função. Um código chamador e uma função podem usar nomes semelhantes sem compartilhar as mesmas variáveis locais.

Mantenha nomes locais dentro de sua chamada

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

make_greeting()

Isso imprime “Hi”. Adicionar print(message) após a chamada gera NameError: name 'message' is not defined: o nome local não está disponível ali. Para disponibilizar o valor ao código chamador, retorne-o e armazene-o:

def make_greeting():
    return "Hi"

message = make_greeting()
print(message)

O message de nível superior é uma nova variável do código chamador que recebe o valor retornado. A função não torna seus próprios nomes locais visíveis fora dela.

Cada chamada recebe novas variáveis locais. Se um corpo define count = 0, soma 1 e o imprime, duas chamadas imprimem “1” e “1”. A segunda chamada não continua com a contagem da primeira. Funções diferentes também podem usar nomes locais como total de forma independente.

Acompanhe o sombreamento e a busca de nomes

x = 10

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

show()
print(x)

A saída é “5” e depois “10”. O x local sombreia o x global dentro de show; a atribuição não altera o valor de nível superior. Uma variável global pertence ao escopo de nível superior do arquivo. Atribuições comuns fora de funções criam variáveis globais.

Para uma função definida no nível superior do arquivo, Python procura um nome entre seus nomes locais, depois entre os globais do arquivo e então entre os nomes embutidos, como print. A primeira correspondência é usada. Portanto, nomes locais e globais são lugares diferentes a verificar quando um valor parece errado.

Reatribuir um parâmetro não altera o nome do código chamador

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

score = 50
add_bonus(score)
print(score)

points começa com o valor 50. Sua reatribuição local faz com que valha 60, então a primeira saída é “60”. O score do código chamador ainda é 50. Para atualizar esse nome explicitamente, use uma função que retorne points + 10 e depois escreva score = add_bonus(score).

Alterar uma lista é outra operação

Uma lista pode ser compartilhada por meio de dois nomes:

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

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

O parâmetro guests e a variável party do código chamador se referem à mesma lista. append altera o conteúdo dessa lista, então a saída é “['Ana', 'Ben']”. Atribuir guests = [] dentro da função faria apenas o nome local apontar para uma nova lista; party ainda se referiria à original. Ao rastrear uma lista passada como argumento, pergunte se a linha altera o objeto compartilhado ou apenas reatribui um nome local.

Uma função pode ler um nome global sem uma declaração. Atribuir um valor a um nome em seu corpo segue uma regra diferente, e confundir essas operações é uma causa comum de UnboundLocalError.

Leia uma configuração fixa

TAX_RATE = 0.25

def tax(amount):
    return amount * TAX_RATE

print(tax(80))

A saída é “20.0”. amount é local; TAX_RATE é lida entre as variáveis globais do arquivo. Letras maiúsculas indicam uma constante por convenção, sinalizando que o programa deve manter a configuração fixa. Python não impõe essa convenção.

A atribuição torna um nome local em todo o corpo

total = 0

def add_to_total(amount):
    total = total + amount

add_to_total(5)

A atribuição torna total local em toda add_to_total. Para calcular o lado direito, Python tenta ler esse nome local antes que ele tenha um valor. Ele não recorre ao total global. A chamada gera UnboundLocalError: cannot access local variable 'total' where it is not associated with a value.

A decisão se baseia no corpo inteiro, não apenas nas linhas já executadas. Um corpo com print(count) seguido de count = 10 também trata count como local na linha de impressão. Um count global não pode fornecer o valor local ausente.

Declare uma atribuição global intencional

total = 0

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

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

Agora tanto a leitura quanto a atribuição se referem ao nome global, então a saída é “12”. Coloque global total antes de qualquer uso de total na função. Usar o nome antes de sua declaração é um erro de sintaxe.

Uma declaração sozinha não cria um valor. Uma atribuição posterior pode criar uma variável global que não existia: o corpo de uma função que contém global level e depois level = 1 cria a variável global level quando chamado.

Mostre a alteração por meio de entradas e de um resultado

O mesmo total acumulado pode ser escrito com uma interface 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)

Isso também imprime “12”. Cada chamada mostra o valor antigo sendo passado, e a atribuição mostra para onde vai o novo valor. Você pode verificar add_to_total(10, 3) por conta própria sem configurar primeiro um estado global oculto. Várias funções alterando a mesma variável global fazem seu comportamento depender da ordem em que são executadas.

Ler uma lista compartilhada e alterar seu conteúdo usa a referência existente. Substituir esse nome global por uma lista diferente é uma atribuição, então a regra de atribuição se aplica.

Quem chama uma função precisa conhecer sua tarefa sem ler toda a implementação. Uma docstring fornece essa descrição. Python reconhece uma string como a docstring da função quando ela é a primeira instrução do corpo.

Escreva primeiro uma descrição curta

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

print(to_fahrenheit.__doc__)

A saída é a frase dentro das aspas. Python armazena a docstring em __doc__; as aspas triplas não fazem parte da frase armazenada. help(to_fahrenheit) exibe a descrição junto com a assinatura to_fahrenheit(celsius). Passe o nome da função para help, sem chamá-la.

A convenção comum é usar três aspas duplas, mesmo para uma docstring de uma linha. Comece com um comando como “Retorne a área de um retângulo.” e termine com um ponto. Mantenha uma descrição curta e suas aspas de fechamento em uma linha. Você não precisa repetir o nome da função e a lista de parâmetros, pois a exibição de ajuda já os inclui.

Acrescente detalhes quando forem necessários para quem chama a função

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

A primeira linha informa o resultado. Uma linha em branco a separa dos detalhes sobre as entradas. O valor padrão é documentado como 0,2, uma fração da conta; isso evita que quem chama a função interprete 20 como o valor pretendido para uma gorjeta de 20 por cento. As aspas de fechamento de uma docstring de várias linhas ficam em uma linha própria.

Para split_bill(84, 4), a função aplica a gorjeta padrão e retorna 25,2. Quem chama a função pode entender o significado das três entradas antes de escolher os argumentos. Inclua unidades quando forem relevantes e descreva efeitos como a impressão, para que seja possível prever tanto o resultado quanto o comportamento visível.

Mantenha a documentação distinta dos comentários

Uma string colocada depois de uma atribuição ou de outra instrução do corpo não é a docstring da função. Ela é uma expressão de string não utilizada, e __doc__ é None se não houver uma docstring como primeira instrução. Um comentário com # também não se torna a descrição de ajuda.

Escreva o resumo enquanto decide a tarefa da função. Se a frase precisar de várias ações sem relação entre si, reconsidere se a função deve ser dividida. Ao alterar parâmetros, valores padrão, valores retornados ou efeitos de impressão, atualize a docstring ao mesmo tempo; quem chama a função depende dela como parte da interface.

Decomposição significa dividir uma tarefa em tarefas menores. Cada função assume a responsabilidade por uma tarefa, com entradas claras e um resultado ou efeito claro. O programa principal pode então ser lido como uma curta sequência de etapas nomeadas.

Planeje os dados antes de escrever os corpos

Para um programa que informa a média de notas de provas e uma nota em letra, identifique três tipos de trabalho: ler notas, calcular uma média e escolher uma nota em letra. Decida o que cada função auxiliar recebe e retorna. Mantenha a exibição em main, onde os resultados são reunidos.

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()

Com as notas 78, 92 e 85, average retorna 85,0. Esse resultado se torna o argumento de letter_grade, que retorna “B”. A exibição é “Average: 85.0 Grade: B”.

main coordena a sequência; ela não precisa saber como letter_grade escolhe sua resposta. Usar uma função por meio de sua tarefa e interface, sem acompanhar cada instrução do corpo, é abstração procedural. Você já usa print dessa maneira.

Dê ao código chamador uma interface clara

A interface de uma função consiste em seu nome, parâmetros, resultado retornado e comportamento documentado. average(a, b, c) exige três números e retorna sua média. O código chamador não precisa ler uma solicitação de entrada nem capturar texto impresso para obter esse número. Você pode reescrever o cálculo mantendo as entradas e a saída combinadas, e as chamadas existentes continuam funcionando.

Use nomes como calculate_total e print_receipt para ações, e is_even ou has_discount para perguntas booleanas. Nomes de parâmetros como price e quantity explicam quais valores pertencem a cada posição. Nomes de uma letra podem ser adequados quando seu significado é claro, como nas três entradas de average.

Transforme repetição em parâmetros

Se várias partes de um programa imprimem títulos diferentes entre as mesmas linhas de sinais de igualdade, faça do título um parâmetro de print_heading(title). A estrutura repetida pertence a um único corpo, enquanto o texto variável pertence às chamadas. Uma alteração posterior no comprimento da linha exige apenas uma edição.

Escolha limites para as funções que tornem as tarefas mais fáceis de entender ou reutilizar. Colocar todas as instruções em uma main longa oculta as tarefas menores. Dividir cada expressão trivial em uma função auxiliar usada uma vez pode adicionar nomes sem melhorar a legibilidade. Um teste útil é verificar se uma frase curta consegue descrever cada tarefa e suas entradas e saídas.

Termine o arquivo com a chamada efetiva main() após todas as definições. Um programa que contém apenas definições criará suas funções e terminará sem executar seus corpos.

Criar várias funções antes de executar qualquer uma delas torna uma falha mais difícil de localizar. Desenvolvimento incremental significa escrever uma pequena parte, verificá-la e depois acrescentar a próxima. Você mantém um programa funcional enquanto reduz a quantidade de código novo a examinar.

Use uma função provisória durante o planejamento

Uma função provisória tem o cabeçalho pretendido e um corpo provisório. Uma docstring e pass mantêm a definição válida, mas a função retorna None até você implementá-la. Um retorno fixo pode ajudar a exercitar a exibição do código chamador sem afirmar que o cálculo real já funciona.

Comece com uma função auxiliar de cálculo cujo resultado você possa determinar independentemente. Quando ela se comportar corretamente, conecte-a à próxima função auxiliar. Deixe a entrada interativa para quando os cálculos puderem ser verificados com chamadas diretas.

Determine os resultados esperados antes de executar

Usando as funções average e letter_grade, as notas 70, 75 e 72 têm média de aproximadamente 72,33, então sua nota esperada é “C”. Verifique as duas etapas:

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

As saídas são “72.33333333333333” e “True”. A comparação testa diretamente a nota esperada; observar apenas a própria saída de um programa sem uma expectativa independente pode deixar passar uma resposta errada, mas plausível.

Teste limites e entradas comuns

Para um valor limiar de 90, teste 90 e 89,9. A função de notas correta retorna “A” e “B”. Se sua primeira condição fosse score > 90, apenas a verificação do valor exato no limite revelaria que 90 passa incorretamente para o próximo teste.

Inclua um valor típico, limites exatos, valores próximos e entradas extremas que a função deve tratar. Para a função de notas, verificar 70 e 0 exercita o limite inferior de aprovação e o caminho final “F”. Uma verificação como print(letter_grade(85) == "B") é fácil porque a função recebe um valor e retorna seu resultado.

Leia o traceback e examine o valor recebido

Suponha que main chame letter_grade(input("Score: ")). Digitar “85” envia uma string para uma comparação com um número. O erro final é TypeError: '>=' not supported between instances of 'str' and 'int'. O traceback aponta para a comparação dentro da função auxiliar, enquanto uma linha anterior de chamada aponta para main.

A falha ocorre na comparação, mas a correção deve ser feita onde a entrada é preparada: converta-a com float() antes de passá-la. Um print("letter_grade got", score) temporário na primeira linha ajuda a revelar uma entrada inesperada. Se o tipo não estiver claro, examine o código chamador e a conversão que ele usa. Remova as impressões de depuração depois que o defeito for corrigido.

Relacione sintomas a causas prováveis

Depois de corrigir uma função auxiliar, execute novamente as verificações que exercitam os caminhos afetados e o código chamador que a conecta ao programa.