Sabe aquele código que você escreveu há dois meses e hoje não entende mais?Isso é mais comum do que parece — e é justamente por isso que comentar bem o seu código é fundamental. Neste post, vamos falar sobre as melhores práticas para comentar e documentar código em Python, além de mostrar como isso pode facilitar a leitura, manutenção e colaboração em projetos de programação.

Muitas vezes, trabalhei em projetos que talvez não terminei ou deixo-os de lado por um tempo. Quando resolvi voltar pra fazer algumas mundanças, me deparei com um código que demorou pra entender. Isso é muito comum.

Outras vezes, quando volto a códigos que trabalhei a dois ou três anos atrás, é mais dificil de entender. Isso é porque os meus hábitos de programação mudaram. Quanto mais tempo passa, mais amador acho que os meus trabalhos do passado são.

Por que Documentação é tão Importante?

Quando você escreve código, é como escrever para uma revista. A história tem que fazer sentido pra todos que estão lendo. A sua audiência começa com você. Mas também inclui outros desenvolvidores.

Claro que um programador conseque ler e entender o código independente de ter comentarios ou não. Mas o comentário ajuda a entender e facilita a interpretação.

Comentários: uma ferramenta essencial no Python

Comentários são uma excelente ferramenta ao trabalhar com Python. Eles ajudam a entender a lógica, as decisões e o propósito do código sem interferir na sua execução. Além disso, tornam o código mais legível e facilitam a colaboração entre desenvolvedores.

Comentário vs. Documentação

Comentários são frequentemente um dos primeiros conceitos aprendidos por quem está começando a programar em Python. Eles oferecem um contexto importante sobre a intenção por trás de cada trecho de código.

Aqui estão quatro razões fundamentais para sempre usar comentários em seus scripts:

  • Documentação: Comentários funcionam como uma forma de documentação, explicando o propósito de funções, classes ou blocos de código. Isso é especialmente útil em algoritmos complexos, onde a lógica nem sempre é óbvia.
  • Legibilidade: Um código bem comentado é mais fácil de ler e entender, especialmente quando for revisitado após algum tempo.
  • Depuração: Comentar temporariamente partes do código é uma prática comum para identificar e isolar bugs.
  • Colaboração: Em projetos em equipe, comentários tornam o código mais acessível, facilitando o entendimento, revisões e contribuições de outros desenvolvedores.

Como usar comentários de linha única em Python

Antes de falarmos sobre como comentar múltiplas linhas, vamos começar com o básico: o comentário de linha única.Em Python, ele começa com o símbolo #, e o interpretador ignora tudo que vier após esse símbolo na mesma linha.

Regras básicas:

  • Posicionamento: Coloque o # no início da linha ou após um trecho de código. Pode ser usado acima do código, ao lado ou de forma isolada.
  • Conteúdo: Após o #, escreva seu comentário. Ele pode ser uma explicação, uma anotação futura ou qualquer informação útil.
# Este é um comentário de linha única explicando a próxima linha de código
print("Hello, world!")  # Isto imprime uma mensagem no console

Método #1: Comentando múltiplas linhas com #

Embora Python não tenha uma sintaxe específica para comentários em bloco, você pode comentar várias linhas usando o # em cada uma delas:

# Exemplo de como comentar múltiplas linhas individualmente
# def exemplo_funcao(nome):
#     # Esta função imprime "Hello" e o nome passado como parâmetro
#     print("Hello", nome)

Método #2: Comentando com aspas triplas

Outra maneira comum de comentar múltiplas linhas é usando strings literais com aspas triplas (''' ou """).Embora não sejam tecnicamente comentários, o interpretador ignora essas strings se não estiverem atribuídas a nenhuma variável.

'''
def exemplo_funcao(nome):
    print("Hello", nome)
'''

Criando um Docstring

Além disso, aspas triplas são muito utilizadas como docstrings — textos de documentação dentro de funções:

# Criando a função exemplo_funcao()
def exemplo_funcao(nome):
    '''
    Esta função recebe um nome e imprime uma saudação no formato "Hello nome"
    '''
    print("Hello", nome)

Conclusão

Comentar seu código em Python é uma prática essencial para qualquer desenvolvedor.Usando comentários de linha única ou docstrings com aspas triplas, você garante clareza e facilidade de manutenção no seu código — tanto para você quanto para sua equipe.

Crie o hábito de comentar desde os primeiros projetos. Com o tempo, isso se tornará parte natural da sua escrita de código — e vai evitar horas de frustração lá na frente!