Como usar comentários em Python?

[

Escrevendo Comentários em Python (Guia)

por Jaya Zhané noções básicas melhores-práticas

Outra forma incrível e fácil de aumentar a legibilidade do seu código é usando comentários!

Neste tutorial, você aprenderá alguns conceitos básicos sobre como escrever comentários em Python. Você aprenderá como escrever comentários que sejam limpos e concisos e quando pode ser desnecessário escrever qualquer comentário.

Você também aprenderá:

Por que é tão importante comentar o seu código
Melhores práticas para escrever comentários em Python
Tipos de comentários que você pode querer evitar
Como praticar escrever comentários mais limpos

Por que Comentar o seu Código é Tão Importante

Comentários são uma parte integral de qualquer programa. Eles podem ser apresentados na forma de docstrings em nível de módulo, ou mesmo explicações inline que ajudam a esclarecer uma função complexa.

Antes de entrar nos diferentes tipos de comentários, vamos dar uma olhada mais de perto em por que comentar o seu código é tão importante.

Considere os dois cenários a seguir, nos quais um programador decidiu não comentar o seu código.

Ao Ler o Seu Próprio Código

O Cliente A deseja um implantação de última hora para o seu serviço da web. Você já está com um prazo apertado, então decide apenas fazer o código funcionar. Toda aquela “coisa extra” - documentação, comentários adequados e assim por diante - você adicionará isso mais tarde.

A data limite se aproxima, e você faz a implantação do serviço, bem na hora. Ufa!

Você faz uma anotação mental para voltar e atualizar os comentários, mas antes de poder incluí-la na sua lista de tarefas, seu chefe chega com um novo projeto em que você precisa começar imediatamente. Em poucos dias, você esqueceu completamente que deveria voltar e comentar corretamente o código que você escreveu para o Cliente A.

Passam-se seis meses, e o Cliente A precisa de um patch criado para aquele mesmo serviço, a fim de cumprir alguns novos requisitos. É o seu trabalho mantê-lo, já que você foi quem o construiu em primeiro lugar. Você abre o seu editor de texto e…

O que você realmente escreveu?!

Você passa horas analisando seu código antigo, mas está completamente perdido na bagunça. Você estava com tanta pressa na época que não nomeou suas variáveis corretamente ou mesmo configurou suas funções no fluxo de controle adequado. E o pior de tudo, você não tem nenhum comentário no script para dizer o que é o quê!

Os desenvolvedores esquecem o que o seu próprio código faz o tempo todo, especialmente se foi escrito há muito tempo ou sob muita pressão. Quando um prazo está se aproximando rapidamente, é fácil se concentrar apenas em fazer o código funcionar, deixando os comentários de lado. No entanto, esse é um erro grave que pode resultar em confusão e dificuldade para entender o código posteriormente.

Ao Ler o Código de Outras Pessoas

Imagine que você está trabalhando em um projeto em equipe e precisa analisar o código escrito por um colega de trabalho. O código está bem organizado e as funções possuem nomes descritivos, mas sem nenhum comentário. Você pode precisar entender como uma função específica funciona ou decifrar a lógica de uma determinada seção do código.

Sem comentários para guiá-lo, você fica perdido e precisa gastar tempo extra lendo e analisando cada parte do código, tentando compreender o raciocínio por trás das decisões tomadas. Isso não apenas atrasa o seu próprio trabalho, mas também pode levar a erros e a um código mal interpretado.

Comentários adequados no código podem salvar um tempo valioso para você e para outras pessoas que precisam ler e entender o código. Eles fornecem insights e explicações adicionais, tornando o código mais fácil de ser compreendido e mantido.

Agora que você entende a importância de comentar seu código, vamos explorar os conceitos básicos de como escrever comentários em Python.

Como Escrever Comentários em Python

Conceitos Básicos de Comentários em Python

Em Python, os comentários são linhas de código que são ignoradas pela interpretação do Python ao executar o programa. Eles são usados para adicionar notas ou explicações para facilitar a compreensão do código por outros programadores.

Em Python, os comentários são precedidos pelo caractere #. Tudo que está após o caractere # na mesma linha é considerado um comentário e será ignorado pelo interpretador Python.

Aqui está um exemplo de como adicionar um comentário em Python:

# Esta é uma linha de comentário

Comentários em Python podem ser usados em diferentes situações, como:

Adicionar uma descrição ao início de um arquivo ou função
Explicar o propósito de uma linha ou bloco de código
Fornecer lembretes ou notas para outros programadores
Comentar partes de código para testar ou desabilitar temporariamente

Comentários Multilinha em Python

Em alguns casos, é necessário adicionar comentários que ocupam várias linhas. Para isso, é possível usar o delimitador ''' ou """ no início e no final do comentário.

Aqui está um exemplo de um comentário multilinha em Python:

'''
Este é um exemplo de comentário multilinha em Python.
Este comentário pode ocupar várias linhas e é ignorado pelo interpretador Python.
É útil quando é necessário fornecer uma explicação mais detalhada para um bloco de código.
'''

A utilização de comentários multilinha é especialmente útil quando se deseja adicionar documentação detalhada a um módulo, função ou classe.

Atalhos de Comentários em Python

Em alguns casos, pode ser necessário comentar um bloco inteiro de código ou desabilitar temporariamente um bloco de código enquanto você está testando seu programa. Para isso, Python fornece atalhos de comentários.

Comentar um bloco inteiro de código ou desabilitar temporariamente um bloco de código é conhecido como “comentário em bloco”. Em Python, você pode usar ''' ou """ para criar um comentário em bloco. Tudo dentro dos delimitadores ''' ou """ será tratado como um comentário e será ignorado pelo interpretador Python.

Aqui está um exemplo de como adicionar um comentário em bloco em Python:

'''
Este é um bloco inteiro de código que está sendo comentado ou desabilitado temporariamente.
print("Este código não será executado.")
print("Este código também não será executado.")
'''

Lembre-se de que, ao comentar um bloco inteiro de código, certifique-se de que o bloco esteja aninhado corretamente. Caso contrário, você pode encontrar erros de indentação na sua programação.

Melhores Práticas para Comentários em Python

Agora que você aprendeu os conceitos básicos de comentários em Python, aqui estão algumas melhores práticas para escrever comentários:

Ao Escrever Código para Si Mesmo

Quando você escreve código para si mesmo, é essencial que seus comentários sejam claros e explicativos o suficiente para ajudá-lo a se lembrar do que o código faz e como ele funciona. Aqui estão algumas dicas:

Comente blocos de código complexos ou partes não triviais do seu código para que você possa se lembrar de como eles funcionam no futuro.
Use nomes de variáveis descritivos e evite abreviações confusas. Isso tornará o seu código mais legível e reutilizável.
Não comente o óbvio, como explicar o que uma função built-in faz. Mantenha os comentários relevantes e informativos.

A ideia é que seus comentários ajudem você a entender e trabalhar com o código mais facilmente no futuro. Portanto, seja claro e conciso nos seus comentários.

Ao Escrever Código para Outras Pessoas

Quando você escreve código para outras pessoas, como parte de um projeto em equipe, você precisa escrever comentários que sejam compreensíveis e úteis para elas. Aqui estão algumas dicas:

Explique o propósito e a lógica de funções e blocos de código complexos para que outros programadores possam entender seu código mais facilmente.
Use comentários para fornecer informações adicionais e contextos que não estejam claros no código por si só.
Certifique-se de que seus comentários estejam atualizados e precisos à medida que você trabalha no código. Comentários desatualizados podem ser confusos e levar a erros.

Lembre-se de que, ao escrever código para outras pessoas, o objetivo é facilitar a compreensão e a participação colaborativa no projeto.

Piores Práticas de Comentários em Python

Assim como existem melhores práticas para escrever comentários, também existem algumas piores práticas que você deve evitar ao comentar seu código em Python. Aqui estão algumas delas:

Evite: Comentários Repetitivos (W.E.T. - Write Everything Twice)

Comentários repetitivos são aqueles que apenas repetem o que está no código. Por exemplo:

# Declaração da variável x
x = 10

Nesse caso, o comentário é desnecessário, pois o código por si só já declara a variável x e é claro para qualquer programador experiente o que isso significa.

Comentários repetitivos apenas poluem o código e não adicionam nenhum valor ou informação adicional. Portanto, evite escrever os mesmos detalhes do código nos comentários.

Evite: Comentários que Cheiram Mal (Smelly Comments)

Comentários que cheiram mal são aqueles que revelam más práticas de programação ou problemas no seu código. Por exemplo:

# Hack: Multiplicar por 2 para obter um resultado correto
result = x * 2

Nesse caso, o comentário indica que há um “hacker” no código para obter um resultado correto. Em vez disso, é melhor corrigir a lógica do código para que ele seja claro e correto, sem a necessidade de um comentário que cheire mal.

Comentários que cheiram mal geralmente indicam que há algo errado com o código ou com a lógica subjacente. Em vez de adicionar comentários que cheiram mal, é melhor refatorar e melhorar o código para que ele seja claro e compreensível por si só.

Evite: Comentários Rudes

Comentários rudes são aqueles que contêm palavras ofensivas, insultos ou qualquer tipo de linguagem inapropriada. Comentários como esses são altamente desrespeitosos e não devem ser aceitos em ambiente de trabalho ou em projetos colaborativos.

Manter um ambiente de trabalho respeitoso é essencial para uma boa colaboração e para construir relacionamentos saudáveis com seus colegas de equipe. Portanto, evite escrever comentários rudes que possam prejudicar a confiança e a comunicação dentro da equipe.

Como Praticar Comentários

A prática de escrever bons comentários em código leva tempo e experiência. Aqui estão algumas maneiras de praticar e melhorar suas habilidades de comentar:

Leia o código escrito por outros desenvolvedores e tente entender seu propósito e lógica sem os comentários. Em seguida, leia novamente com os comentários e compare. Analise se os comentários são úteis e se você pode entender melhor o código com eles.
Refatore seu próprio código antigo e adicione comentários relevantes e explicativos. Compare o código original com o código refatorado e analise como os comentários melhoram a legibilidade e a compreensão do código.
Participe de discussões, fóruns ou grupos de estudo relacionados a Python, onde você pode compartilhar seu código e receber feedback sobre seus comentários. Isso ajudará você a identificar pontos de melhoria e a aprender com outros desenvolvedores.

Lembre-se de que a prática leva à perfeição. Quanto mais você praticar escrever comentários, melhor ficará em comunicar seus pensamentos e intenções no código.

Conclusão

Comentar o seu código é fundamental para a legibilidade, manutenibilidade e colaboração efetiva em projetos de desenvolvimento de software. Com comentários adequados, você pode expressar seus pensamentos, explicar o propósito do código e fornecer informações adicionais para outros programadores que precisam entender e trabalhar no seu código.

Lembre-se de seguir as melhores práticas ao escrever comentários em Python: seja claro e conciso, evite repetições desnecessárias e nunca use linguagem ofensiva ou rudes. Além disso, pratique sempre e procure oportunidades para melhorar suas habilidades de comentar.

Comentários bem escritos contribuem para um código de qualidade e facilitam a vida de todos os envolvidos no projeto. Portanto, não subestime o poder dos comentários e faça deles uma parte essencial do seu processo de desenvolvimento em Python.

Remover anúncios

Outra forma incrível e fácil de aumentar a legibilidade do seu código é usando comentários!

Você também aprenderá:

Por que é tão importante comentar o seu código
Melhores práticas para escrever comentários em Python
Tipos de comentários que você pode querer evitar
Como praticar escrever comentários mais limpos

Por que Comentar o seu Código é Tão Importante

Comentários são partes integrais de qualquer programa. Eles podem se apresentar na forma de docstrings em nível de módulo, ou mesmo explicações em linha que ajudam a esclarecer uma função complexa.

Antes de se aprofundar nos diferentes tipos de comentários, vamos dar uma olhada mais de perto em por que comentar o seu código é tão importante.

Considere os dois cenários a seguir, nos quais um programador decidiu não comentar o seu código.

Ao Ler o Seu Próprio Código

O Cliente A deseja uma implantação de última hora para o serviço da web dele. Você já está com um prazo apertado, então decide apenas fazer com que o código funcione. Toda aquela “coisa extra” - documentação, comentários adequados e assim por diante - você adicionará isso mais tarde.

A data limite chega, e você faz a implantação do serviço, bem na hora. Ufa!

Você faz uma anotação mental para voltar e atualizar os comentários, mas antes de poder incluí-la na sua lista de tarefas, seu chefe aparece com um novo projeto que você precisa começar imediatamente. Em poucos dias, você esqueceu completamente que deveria voltar e comentar corretamente o código que você escreveu para o Cliente A.

Seis meses se passam, e o Cliente A precisa de uma correção desenvolvida para o mesmo serviço, para se adequar a novos requisitos. É seu trabalho fazer a manutenção, já que você foi quem construiu o serviço em primeiro lugar. Você abre o seu editor de texto e…

O que você realmente escreveu?!

Desenvolvedores esquecem o que o seu próprio código faz o tempo todo, especialmente se foi escrito há muito tempo ou sob muita pressão. Quando um prazo está se aproximando rapidamente, é fácil se concentrar apenas em fazer o código funcionar, deixando os comentários de lado. No entanto, esse é um erro grave que pode resultar em confusão e dificuldade para entender o código posteriormente.

Ao Ler o Código de Outras Pessoas

Agora, imagine que você está trabalhando em um projeto em equipe e precisa analisar o código escrito por um colega de trabalho. O código está bem organizado e as funções têm nomes descritivos, mas sem nenhum comentário. Você pode precisar entender como uma função específica funciona ou decifrar a lógica de uma seção específica do código.

Sem comentários para guiá-lo, você se perde e precisa gastar tempo extra lendo e analisando cada parte do código, tentando entender o raciocínio por trás das decisões tomadas. Isso não apenas atrasa o seu próprio trabalho, mas também pode levar a erros e a uma interpretação incorreta do código.

Comentários adequados no código podem economizar tempo valioso para você e para outras pessoas que precisam ler e entender o código. Eles fornecem insights e explicações adicionais, tornando o código mais fácil de ser compreendido e mantido.

Agora que você entende a importância de comentar o seu código, vamos explorar os conceitos básicos de como escrever comentários em Python.

Como Escrever Comentários em Python

Conceitos Básicos de Comentários em Python

Em Python, os comentários são linhas de código que são ignoradas pelo interpretador Python ao executar o programa. Eles são usados para adicionar notas ou explicações que facilitem a compreensão do código por outros programadores.

Em Python, os comentários são precedidos pelo caractere #. Tudo o que vem após o caractere # na mesma linha é considerado um comentário e será ignorado pelo interpretador Python.

Aqui está um exemplo de como adicionar um comentário em Python:

# Este é um comentário em uma linha

Os comentários em Python podem ser usados em diferentes situações, como:

Adicionar uma descrição no início de um arquivo ou função
Explicar o propósito de uma linha ou bloco de código
Fornecer lembretes ou notas para outros programadores
Comentar partes do código para teste ou desabilitação temporária

Comentários Multilinha em Python

Em alguns casos, é necessário adicionar comentários que ocupam várias linhas. Para isso, é possível usar os delimitadores ''' ou """ no início e no final do comentário.

Aqui está um exemplo de um comentário multilinha em Python:

'''
Este é um exemplo de comentário multilinha em Python.
Este comentário pode ocupar várias linhas e será ignorado pelo interpretador Python.
É útil quando é necessário fornecer uma explicação mais detalhada para um bloco de código.
'''

A utilização de comentários multilinha é especialmente útil quando se deseja adicionar documentação detalhada a um módulo, função ou classe.

Atalhos de Comentários em Python

Comentar um bloco inteiro de código ou desabilitar temporariamente um bloco de código é conhecido como “comentário em bloco”. Em Python, você pode usar ''' ou """ para criar um comentário em bloco. Tudo dentro desses delimitadores será tratado como um comentário e será ignorado pelo interpretador Python.

Aqui está um exemplo de como adicionar um comentário em bloco em Python:

'''
Este é um bloco inteiro de código que está sendo comentado ou temporariamente desabilitado.
print("Este código não será executado.")
print("Este código também não será executado.")
'''

Lembre-se de que, ao comentar um bloco inteiro de código, certifique-se de que o bloco esteja aninhado corretamente. Caso contrário, você pode encontrar erros de indentação no seu código.

Melhores Práticas para Comentários em Python

Agora que você aprendeu os conceitos básicos de comentários em Python, aqui estão algumas melhores práticas para escrever comentários:

Ao Escrever Código para Si Mesmo

Comente blocos de código complexos ou partes não triviais do seu código para que você possa se lembrar de como eles funcionam no futuro.
Use nomes descritivos para suas variáveis e evite abreviações confusas. Isso tornará o seu código mais legível e reutilizável.
Não comente o óbvio, como explicar o que uma função embutida faz. Mantenha os comentários relevantes e informativos.

A ideia é que seus comentários ajudem você a entender e trabalhar com o código mais facilmente no futuro. Portanto, seja claro e conciso nos seus comentários.

Ao Escrever Código para Outras Pessoas

Quando você escreve código para outras pessoas, como parte de um projeto em equipe, você precisa escrever comentários que sejam compreensíveis e úteis para elas. Aqui estão algumas dicas:

Explique o propósito e a lógica de funções e blocos de código complexos para que outros programadores possam entender seu código mais facilmente.
Use comentários para fornecer informações adicionais e contexto que não estejam claros no código por si só.
Certifique-se de que seus comentários estejam atualizados e precisos à medida que você trabalha no código. Comentários desatualizados podem ser confusos e levar a erros.

Lembre-se de que, ao escrever código para outras pessoas, o objetivo é facilitar a compreensão e a participação colaborativa no projeto.

Piores Práticas de Comentários em Python

Assim como existem melhores práticas para escrever comentários, há também algumas piores práticas que você deve evitar ao comentar seu código Python. Aqui estão algumas delas:

Evite: Comentários Repetitivos (W.E.T. - Write Everything Twice)

Comentários repetitivos são aqueles que apenas repetem o que está no código. Por exemplo:

# Declaração da variável x
x = 10

Nesse caso, o comentário é desnecessário, pois o código por si só já declara a variável x e é claro para qualquer programador experiente o que isso significa.

Comentários repetitivos apenas poluem o código e não adicionam nenhum valor ou informação adicional. Portanto, evite escrever os mesmos detalhes do código nos comentários.

Evite: Comentários Que Cheiram Mal (Smelly Comments)

Comentários que cheiram mal são aqueles que revelam más práticas de programação ou problemas no seu código. Por exemplo:

# Hack: Multiplicar por 2 para obter um resultado correto
result = x * 2

Nesse caso, o comentário indica que há um “hack” no código para obter um resultado correto. Em vez disso, é melhor corrigir a lógica do código para que ele seja claro e correto, sem a necessidade de um comentário que cheire mal.

Evite: Comentários Rudes

Como Praticar Comentários

A prática de escrever bons comentários em código leva tempo e experiência. Aqui estão algumas maneiras de praticar e aprimorar suas habilidades de comentar:

Leia o código escrito por outros desenvolvedores e tente entender seu propósito e lógica sem os comentários. Em seguida, releia com os comentários e compare. Analise se os comentários são úteis e se você pode entender melhor o código com eles.
Refatore seu próprio código antigo e adicione comentários relevantes e explicativos. Compare o código original com o código refatorado e analise como os comentários melhoram a legibilidade e a compreensão do código.
Participe de discussões, fóruns ou grupos de estudo relacionados a Python, nos quais você pode compartilhar seu código e receber feedback sobre seus comentários. Isso ajudará você a identificar áreas de melhoria e a aprender com outros desenvolvedores.

Lembre-se de que a prática leva à perfeição. Quanto mais você praticar escrever comentários, melhor ficará em comunicar seus pensamentos e intenções no código.

Conclusão

Comentar o seu código é fundamental para a legibilidade, manutenibilidade e colaboração eficaz em projetos de desenvolvimento de software. Com comentários adequados, você pode expressar seus pensamentos, explicar o propósito do código e fornecer informações adicionais para outros programadores que precisam entender e trabalhar no seu código.

Lembre-se de seguir as melhores práticas ao escrever comentários em Python: seja claro e conciso, evite repetições desnecessárias e nunca use linguagem ofensiva ou rude. Além disso, pratique sempre e procure oportunidades para aprimorar suas habilidades de comentar.