Código Python limpo: comentários, docstrings e PEP 8

Iniciante15 min4 exercícios90 XP

Este tutorial foi traduzido do original em inglês.Read in English Leer en español Читать на русском อ่านภาษาไทย Avisar sobre um erro de tradução

Antes de começar

Conversão de tipos em Python: como converter tipos de dados

0/4 exercícios

Imagine abrir um livro de receitas em que cada receita foi rabiscada com uma letra bagunçada, sem títulos, sem lista de ingredientes e sem espaço entre os passos. Você até conseguiria entender tudo uma hora, mas seria sofrido. Com código acontece a mesma coisa.

Programadores profissionais passam muito mais tempo lendo código do que escrevendo. Robert C. Martin, autor do livro Clean Code, diz que essa proporção é bem maior que 10 para 1. Ou seja, deixar o seu código fácil de ler é uma das habilidades mais valiosas que você pode aprender.

Neste tutorial, você vai aprender a escrever um Python que outras pessoas (e você mesmo, no futuro) vão gostar de ler. Vamos ver comentários, docstrings, convenções de nomes e a PEP 8, o guia de estilo oficial do Python.

Por que código limpo importa?

Pense em um quarto bagunçado. Você sabe que as suas coisas estão lá em algum lugar, mas achar qualquer coisa leva uma eternidade. Código limpo é como um quarto arrumado: cada coisa tem o seu lugar, e você encontra o que precisa rapidamente.

Se você escreve um código hoje e volta a ele daqui a duas semanas, vai ter esquecido o que metade dele faz. Um código claro e bem organizado funciona como um mapa para o seu eu do futuro.

Código limpo também faz diferença quando você trabalha com outras pessoas. Em uma equipe, todo mundo precisa entender o código de todo mundo. Código bagunçado atrasa a equipe inteira.

Código bagunçado x código limpo: mesmo resultado, experiência muito diferente

# Which version would you rather read?

# Version A

x = 3.14159

y = 10

z = x * y * y

print(z)

# Version B

pi = 3.14159

radius = 10

circle_area = pi * radius * radius

print(f"Area of circle: {circle_area}")

Saída

314.159
Area of circle: 314.159

As duas versões calculam a mesma coisa. Mas a versão B mostra o que o código faz sem precisar de nenhuma explicação extra. Os nomes das variáveis são a documentação.

Como escrever bons comentários em Python

Você já sabe que comentários começam com # e que o Python os ignora. Mas saber quando e como usar comentários é o que separa o código de iniciante do código profissional.

Um bom comentário explica por que algo é feito, e não o que o código faz. Se o seu código estiver claro o bastante, o "o quê" fica evidente só de lê-lo.

❌ Comentários ruins (explicam o óbvio)

# Set x to 5
x = 5

# Add 1 to x
x = x + 1

# Print x
print(x)

✓ Comentários bons (explicam o porquê)

# Start with 5 retries (server sometimes drops first request)
retry_count = 5

# Move to next attempt
retry_count = retry_count + 1

print(retry_count)

Percebeu a diferença? Os comentários ruins só repetem o que o código já diz. Os bons contam por que o código existe e dão um contexto que você não teria lendo apenas o código.

Quando você deve comentar o seu código Python?

Comente quando o código faz algo surpreendente ou pouco óbvio. Se alguém lendo o seu código diria "espera, por quê?", é aí que cabe um comentário.

Comentários que realmente ajudam

# Good reasons to comment:

price = 9.99

tax = price * 0.0825 # Texas sales tax rate (8.25%)

# Multiply by 100 to avoid floating-point rounding errors

price_in_cents = int(price * 100)

# TODO: Replace with database lookup once API is ready

user_name = "Guest"

Saída

(sem saída)

Use comentários também para notas TODO: lembretes de coisas que você pretende corrigir ou melhorar depois. A maioria dos editores de código destaca os comentários TODO para que sejam fáceis de encontrar.

Quando você deve evitar comentários?

Se você sente necessidade de escrever um comentário explicando o que o código faz, isso geralmente é sinal de que o próprio código deveria ser mais claro. Nomes de variáveis melhores muitas vezes eliminam de vez a necessidade de comentários.

❌ O comentário esconde um código confuso

# Calculate the final price with 20% discount
p = x - (x * 0.2)

✓ Código claro dispensa comentário

discount_rate = 0.20
final_price = original_price - (original_price * discount_rate)

O que são docstrings em Python?

Uma docstring é uma string especial que descreve o que uma função, classe ou módulo faz. Ela fica logo no início do corpo da função, entre aspas triplas (""").

Pense na docstring como o manual de instruções que vem com um produto. Você não precisa abrir o produto para saber o que ele faz: é só ler o manual.

Uma função com uma docstring bem feita

def calculate_tip(bill_amount, tip_percent):

"""Calculate the tip amount for a restaurant bill.

Args:

bill_amount: The total bill in dollars.

tip_percent: The tip percentage (e.g., 20 for 20%).

Returns:

The tip amount in dollars.

"""

return bill_amount * (tip_percent / 100)

# Using the function

tip = calculate_tip(50.00, 20)

print(f"Tip: ${tip:.2f}")

# You can view any function's docstring with help()

help(calculate_tip)

Saída

Tip: $10.00
Help on function calculate_tip in module __main__:

calculate_tip(bill_amount, tip_percent)
    Calculate the tip amount for a restaurant bill.

    Args:
        bill_amount: The total bill in dollars.
        tip_percent: The tip percentage (e.g., 20 for 20%).

    Returns:
        The tip amount in dollars.

Quando você chama help() em uma função, o Python exibe a docstring dela. É assim também que funções embutidas como print() e len() mostram a própria documentação.

Para funções curtas e simples, uma docstring de uma linha é suficiente. Para funções mais complexas, descreva os argumentos e o que a função retorna.

Uma docstring simples, de uma linha

# Simple function - one-line docstring is fine

def square(n):

"""Return the square of a number."""

return n * n

print(square(7))

print(square(12))

Saída

49
144

Convenções de nomes em Python: como nomear variáveis

Escolher bons nomes é uma das partes mais difíceis da programação. Um ótimo nome de variável é como uma boa etiqueta em uma caixa: você sabe exatamente o que tem dentro sem precisar abri-la.

O Python usa um estilo chamado snake_case para nomes de variáveis e funções. As palavras ficam em minúsculas e são separadas por sublinhados.

Convenções de nomes do Python na prática

# snake_case - the Python way

user_name = "Alice"

total_price = 29.99

is_logged_in = True

max_retry_count = 3

# Use these in practice

print(f"User: {user_name}")

print(f"Total: ${total_price}")

print(f"Logged in: {is_logged_in}")

print(f"Max retries: {max_retry_count}")

Saída

User: Alice
Total: $29.99
Logged in: True
Max retries: 3

Estas são as principais convenções de nomes que os programadores Python seguem:

Convenções de nomes para cada tipo de coisa

# Variables and functions: snake_case

player_score = 100

def calculate_average(numbers):

"""Return the average of a list of numbers."""

return sum(numbers) / len(numbers)

# Constants: UPPER_SNAKE_CASE

MAX_SPEED = 120

PI = 3.14159

DATABASE_URL = "localhost:5432"

# Classes: PascalCase (you'll learn classes later)

# class PlayerCharacter:

# class ShoppingCart:

print(f"Player score: {player_score}")

print(f"Max speed: {MAX_SPEED}")

print(f"Pi: {PI}")

Saída

Player score: 100
Max speed: 120
Pi: 3.14159

Como escolher nomes de variáveis significativos

O nome de uma variável deve descrever o que o valor representa, e não de que tipo ele é. O objetivo é que o seu código se leia como uma frase.

❌ Nomes vagos ou enigmáticos

x = "Alice"
n = 25
f = True
temp = 3
data = 98.6
my_list = ["math", "science"]

✓ Nomes descritivos e significativos

student_name = "Alice"
student_age = 25
is_enrolled = True
max_attempts = 3
body_temperature = 98.6
course_list = ["math", "science"]

Nomes de uma letra só, como x, n e i, funcionam bem em fórmulas matemáticas curtas ou em laços bem pequenos. Para todo o resto, use um nome de verdade, que explique para que a variável serve.

O que é a PEP 8? O básico do guia de estilo do Python

A PEP 8 é o guia de estilo oficial do Python. PEP quer dizer "Python Enhancement Proposal" (proposta de melhoria do Python), e a de número 8 é a que trata do estilo de código. É como um uniforme para o código Python: todo mundo segue as mesmas regras, e assim qualquer código Python parece familiar.

Você não precisa decorar todas as regras. Estas são as que mais importam quando você está começando.

Como usar a indentação em Python (4 espaços)

O Python usa a indentação para agrupar o código. O padrão é 4 espaços por nível. Nunca misture tabulações e espaços: escolha um deles (espaços) e mantenha sempre o mesmo.

Indentação correta com 4 espaços

# Correct: 4 spaces for each indentation level

def greet(name):

"""Print a greeting message."""

if name:

message = f"Hello, {name}!"

print(message)

else:

print("Hello, stranger!")

greet("Alice")

greet("")

Saída

Hello, Alice!
Hello, stranger!

Como usar linhas em branco no código Python

Linhas em branco são como as quebras de parágrafo em uma redação. Elas separam ideias diferentes e deixam o código mais fácil de percorrer com os olhos.

Linhas em branco para separar seções

# Two blank lines before a function definition

def calculate_area(width, height):

"""Calculate the area of a rectangle."""

return width * height

def calculate_perimeter(width, height):

"""Calculate the perimeter of a rectangle."""

return 2 * (width + height)

# Use the functions

area = calculate_area(5, 3)

perimeter = calculate_perimeter(5, 3)

print(f"Area: {area}")

print(f"Perimeter: {perimeter}")

Saída

Area: 15
Perimeter: 16

Use duas linhas em branco antes e depois das definições de função no nível principal do arquivo. Use uma linha em branco para separar os trechos lógicos dentro de uma função.

Como usar espaços em volta dos operadores em Python

Coloque um espaço de cada lado de operadores como =, +, -, == e !=. Isso deixa o código muito mais fácil de ler à primeira vista.

❌ Sem espaços (difícil de ler)

total=price*quantity+tax
is_valid=age>=18 and name!=""
result=x**2+y**2

✓ Espaços em volta dos operadores (fácil de ler)

total = price * quantity + tax
is_valid = age >= 18 and name != ""
result = x**2 + y**2

Erros comuns de estilo em Python e como corrigi-los

Vamos ver os erros de estilo mais comuns entre iniciantes e como corrigi-los. São mudanças pequenas que fazem uma grande diferença na legibilidade.

❌ Comparar diretamente com True/False/None

if is_active == True:
    print("Active")

if result == None:
    print("No result")

✓ Use o jeito pythônico

if is_active:
    print("Active")

if result is None:
    print("No result")

Não compare com True ou False usando ==. Use a variável diretamente. Para None, use sempre is None em vez de == None.

❌ Estilo inconsistente

userName = "Alice"      # camelCase
total_Price = 29.99     # mixed style
def CalculateTotal():   # PascalCase for function
    pass

✓ snake_case consistente

user_name = "Alice"     # snake_case
total_price = 29.99     # snake_case
def calculate_total():   # snake_case
    pass

Escolha um estilo e seja consistente. Em Python, esse estilo é snake_case para variáveis e funções. Misturar estilos deixa o código com cara de bagunça.

❌ Linhas em branco demais ou nenhuma

def add(a, b):
    return a + b
def subtract(a, b):
    return a - b
def multiply(a, b):
    return a * b

✓ Duas linhas em branco entre funções

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


def subtract(a, b):
    return a - b


def multiply(a, b):
    return a * b

Linters de Python: ferramentas que verificam o seu estilo automaticamente

Você não precisa decorar todas as regras da PEP 8. Ferramentas chamadas linters verificam automaticamente se o seu código tem problemas de estilo. Pense no linter como um corretor ortográfico, só que para o estilo do código.

Estes são os linters de Python mais populares, e mais um formatador:

flake8: verifica violações da PEP 8 e erros comuns. Ótimo para iniciantes.

pylint: mais minucioso. Também dá sugestões sobre a qualidade do código.

ruff: o novato da turma. Muito rápido, reúne várias ferramentas em uma.

black: não é um linter, e sim um formatador automático. Em vez de avisar você, ele corrige o seu estilo automaticamente.

A maioria dos editores de código (como o VS Code) consegue rodar linters em segundo plano e sublinhar os problemas de estilo enquanto você digita. É como ter um treinador de estilo sentado ao seu lado.

Exercícios práticos

Hora de praticar! Estes exercícios vão ajudar você a criar o hábito de escrever código Python limpo e legível.

Exercício 1: adicione comentários e uma docstring

Escreva o código

Escreva uma função chamada celsius_to_fahrenheit que recebe uma temperatura em Celsius e retorna o valor em Fahrenheit.

A fórmula é: fahrenheit = celsius * 9/5 + 32

A sua função precisa ter:

Uma docstring descrevendo o que ela faz

Um comentário explicando a fórmula

Retorne o valor sem exibi-lo: as verificações chamam a sua função e exibem o que ela retorna. Para 100 graus Celsius, o resultado é:

212.0

# Write your function with a docstring and comment

Exercício 2: corrija os nomes ruins de variáveis

Corrija o erro

Este código funciona, mas os nomes das variáveis são péssimos! Ninguém consegue saber o que x, y, z, a e b significam.

Dê às variáveis nomes significativos e use snake_case. O código calcula o pagamento semanal de um trabalhador. A saída precisa continuar exatamente igual:

Weekly pay: $450.0
With overtime: $562.5

x = 15.0

y = 30

z = x * y

a = 5

b = x * 1.5 * a

print(f"Weekly pay: ${z}")

print(f"With overtime: ${z + b}")

Exercício 3: reescreva um código bagunçado no estilo da PEP 8

Escreva o código

O código abaixo está bagunçado. Reescreva-o seguindo as regras da PEP 8:

def calcArea(W,H):
  result=W*H
  return result
def calcPerimeter(W,H):
  result=2*(W+H)
  return result
w=8
h=5
print(f"Area: {calcArea(w,h)}")
print(f"Perimeter: {calcPerimeter(w,h)}")

Corrija estes problemas:

Os nomes das funções devem estar em snake_case

Use 4 espaços de indentação

Coloque espaços em volta dos operadores e depois das vírgulas

Coloque duas linhas em branco entre as definições de função

Use nomes de variáveis significativos

A saída deve ser:

Area: 40
Perimeter: 26

# Rewrite the messy code from the instructions above, following PEP 8 rules

Exercício 4: refatore e limpe este código

Melhore o código

Esta função funciona, mas está bagunçada. Refatore-a para que fique limpa e profissional:

def d(p,r):
  a=p*r/100
  t=p-a
  return t
print(d(200,15))

A sua versão refatorada precisa:

Dar à função um nome significativo (ela calcula um preço com desconto)

Usar nomes de parâmetros descritivos

Ter uma docstring explicando o que a função faz

Usar o espaçamento da PEP 8 (indentação de 4 espaços, espaços em volta dos operadores)

Ter duas linhas em branco antes da chamada da função

A saída deve ser:

170.0

# Refactor the messy code into clean, professional Python

Resumo: o que você aprendeu sobre código Python limpo

Agora você conhece os hábitos que separam o código de iniciante do código profissional. Aqui vai uma referência rápida:

Conceito	Regra principal	Exemplo
Comentários (`#`)	Explique o porquê, não o quê	`# Texas tax rate (8.25%)`
Docstrings (`"""`)	Descreva o que a função faz	`"""Convert Celsius to Fahrenheit."""`
Nomes de variáveis	Descritivos, em `snake_case`	`total_price`, `is_valid`
Constantes	`UPPER_SNAKE_CASE`	`MAX_SPEED = 120`
Indentação	Sempre 4 espaços	`def greet():` e depois 4 espaços
Linhas em branco	2 entre funções	Separam trechos lógicos
Operadores	Espaços em volta de `=`, `+` etc.	`x = a + b`
PEP 8	O guia de estilo oficial do Python	Consistência acima de tudo

Código limpo não tem a ver com ser sofisticado. Tem a ver com ser gentil: com os seus colegas de equipe, com você mesmo no futuro e com qualquer pessoa que leia o seu código. Comece a criar esses hábitos agora, e eles vão acompanhar você durante toda a sua carreira em programação.

O que vem a seguir?

Você terminou a seção de fundamentos do Python! Agora você tem uma base sólida no básico da linguagem. A seguir, você vai entrar em Controle de fluxo, onde vai aprender a fazer os seus programas tomarem decisões com instruções if e repetirem ações com laços.

Por que código limpo importa?

Como escrever bons comentários em Python

Quando você deve comentar o seu código Python?

Quando você deve evitar comentários?

O que são docstrings em Python?

Convenções de nomes em Python: como nomear variáveis

Como escolher nomes de variáveis significativos

O que é a PEP 8? O básico do guia de estilo do Python

Como usar a indentação em Python (4 espaços)

Como usar linhas em branco no código Python

Como usar espaços em volta dos operadores em Python

Erros comuns de estilo em Python e como corrigi-los

Linters de Python: ferramentas que verificam o seu estilo automaticamente

Exercícios práticos

Resumo: o que você aprendeu sobre código Python limpo

O que vem a seguir?

Tutoriais relacionados