Comentários, nomes e legibilidade

Objetivo da aula

Escrever código simples que outra pessoa consiga compreender.

Regra desta aula: vamos assumir que você nunca viu este assunto antes. Nenhum termo importante será usado sem explicação e todo exemplo deve ser entendido linha por linha, não apenas copiado.

Começando do zero

Código é lido muito mais vezes do que é escrito. Nomes claros, organização consistente e comentários úteis diminuem a quantidade de coisas que a pessoa precisa “adivinhar” ao ler um programa. Legibilidade não é decoração: ela ajuda a encontrar erros e a manter o software.

Uma imagem mental para entender

Compare duas caixas: uma rotulada “coisas” e outra rotulada “material_escolar”. As duas podem guardar objetos, mas a segunda já informa a intenção. Nomes de variáveis funcionam como rótulos: quanto melhor o rótulo, menos esforço para descobrir o que aquele valor representa.

Conceitos essenciais, sem pular etapas

Identificador

É o nome usado para referenciar algo no código, como uma variável ou função. Em Python, nomes podem conter letras, números e sublinhado, mas não podem começar por número e não devem usar palavras reservadas como if ou for.

Nomes que explicam intenção

preco_final comunica muito mais que x. Em exercícios minúsculos, nomes curtos podem aparecer, mas em código real o nome deve ajudar a entender o papel do valor.

Comentários

Um comentário começa com #. O interpretador ignora o restante da linha. Comentários são úteis para explicar contexto, decisão ou motivo. Um comentário que apenas repete a linha não acrescenta informação.

Consistência

Python costuma usar snake_case para nomes de variáveis e funções: palavras minúsculas separadas por sublinhado, como tempo_total. Seguir um padrão torna o código previsível.

Modelo mental

INTENÇÃO → NOMES CLAROS → ESTRUTURA CONSISTENTE → LEITURA MAIS FÁCIL → MENOS ERROS

Exemplo 1 — primeiro veja o programa inteiro

# Desconto usado na campanha de boas-vindas
taxa_desconto = 0.10
preco_original = 80.00
valor_desconto = preco_original * taxa_desconto
preco_final = preco_original - valor_desconto

print("Preço final:", preco_final)

Agora vamos ler linha por linha

O comentário explica por que a taxa existe; não diz apenas “cria taxa”.
taxa_desconto, preco_original e preco_final deixam a regra visível sem precisar decorar o significado de letras.
Uma linha em branco separa o cálculo da apresentação do resultado.
O programa continua simples, mas já está organizado para outra pessoa ler.

Saída esperada

Preço final: 72.0

Exemplo 2 — o mesmo conceito em outra situação

# Versão difícil de ler
x = 80
y = 0.10
z = x - x * y
print(z)

As duas versões podem produzir o mesmo número, mas a segunda esconde a intenção. O problema não é “funcionar ou não”; é o custo de entender e modificar depois.

Experimento guiado

Não pule esta parte. Programação só começa a fazer sentido quando você prevê um resultado, executa e compara a previsão com o que realmente aconteceu.

Reescreva o segundo exemplo usando nomes que expliquem o significado de cada valor.
Crie um comentário que registre a razão de uma regra de negócio inventada.
Leia seu código em voz alta. Se precisar dizer “esse x aqui significa…”, o nome provavelmente pode melhorar.
Use sempre o mesmo padrão de nomes ao longo do exercício.

Mini desafio

Reescreva a = 10; b = 3; c = a * b como um pequeno cálculo de quantidade e preço, usando nomes claros e um comentário contextual.

Solução comentada

# Exemplo: três unidades de um produto de R$ 10
preco_unitario = 10
quantidade = 3
total = preco_unitario * quantidade
print("Total:", total)

Depois de executar a solução, altere pelo menos um valor e explique por que o novo resultado mudou. Se você só copiou e não consegue explicar cada linha, refaça o desafio em uma versão menor.

Erros comuns e por que acontecem

Usar x, y, z para tudo e obrigar o leitor a decorar significados.
Escrever comentários como # soma 1 em cima de contador = contador + 1; isso repete o óbvio.
Usar espaços, hífens ou acentos em identificadores de forma inconsistente. Python aceita Unicode em identificadores, mas em projetos técnicos a convenção simples costuma facilitar interoperabilidade e digitação.
Criar nomes enormes que viram frases. Clareza não significa escrever um parágrafo dentro do nome.

Cheque se você realmente entendeu

Qual é melhor: `p` ou `preco_total`?

Resposta: preco_total, quando esse é realmente o papel do valor, porque comunica intenção.

Comentário deve dizer o que cada caractere faz?

Resposta: Não. O código já mostra o “o quê”; o comentário é mais valioso para contexto e “por quê”.

O que é `snake_case`?

Resposta: Um padrão como preco_final, com palavras minúsculas separadas por sublinhado.

Resumo em linguagem simples

Nesta aula, o ponto central foi Comentários, nomes e legibilidade. Tente explicar o modelo INTENÇÃO → NOMES CLAROS → ESTRUTURA CONSISTENTE → LEITURA MAIS FÁCIL → MENOS ERROS sem olhar a tela. Depois, escreva um exemplo próprio menor que os apresentados. Esse exercício de explicação é parte do aprendizado, não um extra.

Conexão com a próxima aula

Na próxima aula, Executar, observar, alterar, repetir, vamos aproveitar exatamente o que foi construído aqui. Você não precisa memorizar tudo; precisa conseguir reconhecer o conceito e reconstruí-lo com raciocínio e testes.

Comentários, nomes e legibilidade