Os comentários em Python são uma das ferramentas mais simples, mas também mais poderosas para quem está aprendendo a programar. Eles servem para explicar o que o código faz, facilitar a leitura e ajudar outros desenvolvedores (ou até você mesmo no futuro) a entender o raciocínio por trás de um trecho de código.
Neste artigo, você vai aprender como, quando e por que usar comentários em Python, com exemplos claros, boas práticas e erros comuns a evitar.
O que são comentários em Python?
Comentários são linhas de texto dentro do código que o Python ignora completamente quando executa o programa.
Eles servem apenas para humanos lerem — não para o computador.
Em outras palavras, comentários não afetam o funcionamento do programa. Eles são como anotações que ajudam a descrever o que está acontecendo.
Exemplo simples:
Python
# Este programa exibe uma mensagem de boas-vindas
print("Olá, mundo!")Saída:
Olá, mundo!
O texto depois do símbolo # é o comentário. Ele não é executado. O Python lê, entende que é um comentário, e simplesmente ignora.
Como criar comentários em Python
Existem dois tipos principais de comentários em Python: comentários de linha única e comentários de múltiplas linhas.
1. Comentários de linha única
Para criar um comentário de linha única, basta usar o símbolo # seguido do texto que deseja escrever.
Exemplo:
Python
# Calcula o dobro de um número
numero = 5
resultado = numero * 2
print(resultado)O # indica que tudo à direita dele será ignorado pelo interpretador Python.
2. Comentários de múltiplas linhas
Se precisar escrever uma explicação maior, há duas opções:
Opção 1: usar # em todas as linhas
Python
# Este programa calcula o valor final
# de um produto aplicando um desconto.
preco = 100
desconto = 0.1
preco_final = preco - (preco * desconto)
print(preco_final)Opção 2: usar aspas triplas (""" ou ''')
Embora o Python interprete textos entre aspas triplas como strings de múltiplas linhas, se você as usar fora de uma variável ou função, elas podem servir como comentário de bloco.
Python
"""
Este trecho calcula o preço final
de um produto com desconto.
"""
preco = 100
desconto = 0.1
print(preco - (preco * desconto))Por que usar comentários no seu código?
Você pode pensar: “Mas o código não deveria se explicar sozinho?”.
Sim, idealmente, o código deve ser claro e bem escrito. No entanto, comentários complementam a clareza, ajudando a entender o porquê de uma decisão, não apenas o que o código faz.
Principais benefícios:
- Facilitam a leitura — especialmente para iniciantes.
- Ajudam na manutenção — entender o que você fez semanas atrás.
- Melhoram o trabalho em equipe — outros desenvolvedores compreendem o raciocínio.
- Servem como documentação rápida — explicam partes importantes sem precisar de um arquivo à parte.
Boas práticas ao escrever comentários
Escrever comentários é fácil. Escrever bons comentários é o verdadeiro desafio.
Veja algumas boas práticas que ajudam a deixar seu código profissional e limpo.
1. Seja claro e direto
Evite frases longas ou confusas. Vá direto ao ponto.
❌ Ruim:
# Aqui estamos multiplicando o valor do número por 2 para conseguir o resultado final que será impresso abaixo✅ Bom:
# Multiplica o número por 22. Explique o "porquê", não o "como"
O código já mostra “como” algo é feito. Use o comentário para explicar o “porquê”.
❌ Ruim:
# Subtrai o desconto do preço
preco_final = preco - desconto✅ Bom:
# Aplica o desconto promocional de 10%
preco_final = preco - desconto3. Atualize os comentários
Comentários desatualizados podem causar confusão. Sempre revise se o texto ainda descreve o código corretamente.
4. Evite comentários óbvios
Não é necessário explicar algo que já está claro.
❌ Ruim:
Python
# Soma 2 e 2
print(2 + 2)✅ Bom:
Use comentários apenas quando houver um raciocínio ou contexto importante.
5. Use docstrings em funções e classes
Além dos comentários simples, Python tem uma forma especial de documentação: as docstrings.
Docstrings são textos entre aspas triplas usados logo após a definição de uma função, classe ou módulo.
Eles servem para explicar o que a função faz, seus parâmetros e o retorno.
Exemplo:
Python
def somar(a, b):
"""
Retorna a soma de dois números.
Parâmetros:
a (int ou float): primeiro número
b (int ou float): segundo número
"""
return a + b
print(somar(3, 4))Docstrings são úteis porque podem ser acessadas com a função help():
help(somar)Saída:
Help on function somar in module __main__:
somar(a, b)
Retorna a soma de dois números.
Comentários em código real
Veja um exemplo completo, mais próximo de um programa real:
Python
# Sistema simples de login
# Armazena o usuário e senha corretos
usuario_correto = "admin"
senha_correta = "1234"
# Solicita dados do usuário
usuario = input("Usuário: ")
senha = input("Senha: ")
# Verifica se estão corretos
if usuario == usuario_correto and senha == senha_correta:
print("Login bem-sucedido!")
else:
print("Usuário ou senha incorretos.")Neste código, os comentários guiam o leitor passo a passo, explicando o que cada bloco faz.
Isso é fundamental em projetos maiores, onde o raciocínio pode se perder sem boas anotações.
Quando evitar comentários
Nem sempre é necessário comentar. Em alguns casos, comentários podem poluir o código ou atrapalhar a leitura.
Evite:
- Comentar cada linha desnecessariamente.
- Repetir o que o código já deixa claro.
- Escrever comentários muito longos.
- Usar comentários para “desativar” código (prefira apagar ou versionar).
Comparação entre comentários e docstrings
| Tipo | Símbolo usado | Onde é usado | Objetivo principal |
|---|---|---|---|
| Comentário comum | # | Qualquer parte do código | Explicar trechos ou decisões |
| Docstring | """ """ | Funções, classes e módulos | Documentar comportamento e parâmetros |
Ambos são importantes, mas têm propósitos diferentes.
Comentários explicam trechos do código; docstrings explicam funcionalidades completas.
Dicas para usar comentários com inteligência
- Comente antes de codar — escrever o que a função deve fazer ajuda no planejamento.
- Use uma linguagem simples — imagine que alguém iniciante vai ler seu código.
- Pense no futuro — o código pode ser revisado meses depois.
- Evite sarcasmo ou piadas — comentários devem ser profissionais.
- Use o mesmo idioma — mantenha os comentários todos em português ou todos em inglês.
Erros comuns ao usar comentários
Mesmo programadores experientes cometem deslizes.
Veja alguns erros que você deve evitar desde o início:
- Escrever comentários sem sentido (“faz algo aqui”).
- Copiar e colar comentários de outro código sem revisar.
- Esquecer de atualizar comentários após mudar o código.
- Usar comentários apenas para “encher espaço”.
Lembre-se: um comentário ruim é pior do que nenhum.
Conclusão
Aprender a usar comentários em Python é essencial para desenvolver códigos organizados, legíveis e profissionais.
Eles são simples de escrever, mas têm grande impacto na qualidade e manutenção do projeto.
Ao longo do tempo, você perceberá que bons comentários contam uma história: a história de como e por que o seu código foi criado.
Portanto, use comentários para ajudar quem vai ler seu código — inclusive o “você do futuro”.
Perguntas Frequentes (FAQ)
1. O que é um comentário em Python?
É uma linha de texto que o Python ignora, usada para explicar o código.
2. Como criar um comentário em Python?
Use o símbolo # antes do texto que deseja comentar.
3. O Python executa comentários?
Não. Comentários são ignorados durante a execução.
4. Qual a diferença entre # e aspas triplas?
O # é para uma linha; aspas triplas podem criar blocos maiores.
5. Posso usar comentários em qualquer lugar?
Sim, mas use com moderação e apenas quando forem úteis.
6. O que é uma docstring?
É um texto entre aspas triplas usado para documentar funções e classes.
7. Comentários afetam o desempenho do programa?
Não. O Python os ignora completamente.
8. Devo comentar cada linha do código?
Não. Comente apenas o necessário para explicar o raciocínio.
9. Comentários podem estar em português?
Sim. Use o idioma mais compreensível para sua equipe.
10. O que acontece se eu deixar comentários antigos?
Eles podem causar confusão. Sempre atualize seus comentários.
11. É errado usar comentários longos?
Depende. Prefira textos curtos e diretos sempre que possível.
12. Como ver docstrings no Python?
Use a função help(nome_da_funcao) no terminal.
