Como comentar em Python – um guia rápido para iniciantes

Comentários são uma parte essencial de qualquer linguagem de programação, incluindo Python. Eles ajudam você e outros desenvolvedores a entender a lógica e a funcionalidade do seu código. Quando você adiciona comentários ao seu código Python, isso não apenas ajuda a explicar seu código, mas também melhora sua legibilidade, qualidade e facilidade de manutenção.

Neste tutorial do Python, exploraremos como escrever um comentário de uma única linha, comentários de várias linhas e strings de várias linhas. Vamos nos aprofundar em uma visão geral detalhada do uso de comentários em seu programa Python, entender os diferentes tipos de comentários Python e vários casos de uso para cada tipo de comentário. Isso incluirá exemplos que demonstram como escrever bons comentários, adicionar comentários embutidos e evitar escrever código mal escrito.

Vamos entrar nisso.

Índice

• O que são comentários de linha única?
• O que são comentários de várias linhas?
  • Usando aspas triplas
  • Usando um símbolo de hash com continuação de linha
• O que são comentários embutidos?
• O que são Docstrings?
  • Documentação de função e método
  • Class Docstrings
  • Módulo Docstrings
• Melhores práticas para escrever comentários
  • Clareza e Concisão
  • Evitando Comentários Óbvios
  • Atualizando comentários como alterações de código
• Conclusão

O que são comentários de linha única?

Na programação Python , um comentário de linha única é criado usando o caractere hash (#) no início de uma linha. Qualquer texto que segue o símbolo de hash na mesma linha é tratado como um comentário de linha única e o interpretador Python não o executará.

Existem dois propósitos principais para usar comentários de linha única no código Python:

1. Fornecer uma breve explicação ou resumo de uma linha do segmento específico do código Python, oferecendo informações sobre a função ou propósito do código.

2. Desativar temporariamente a execução de uma única linha de código, o que é útil durante a depuração ou teste, sem remover permanentemente o código do seu script.

Veja a seguir um exemplo de como escrever comentários para explicar o código Python em uma única linha:

Neste exemplo, cada comentário de linha única oferece explicações para cada linha de código, tornando mais fácil para você e outros desenvolvedores entenderem a finalidade do código.

O código Python abaixo demonstra como escrever comentários para evitar que uma única linha de código seja executada:

No exemplo acima, a instrução de impressão do console com strings literais, destinada a fins de depuração, foi comentada para impedir sua execução quando o código for executado. O comentário de linha única garante que o interpretador Python trate a linha como um comentário, em vez de um pedaço de código.

Comentar linhas específicas de código pode ser benéfico quando você está depurando e resolvendo erros.

Adotar o hábito de escrever comentários de linha única claros, concisos e relevantes é uma boa prática, pois ajuda a focar na explicação de aspectos específicos do seu código. Ao elaborar comentários bem escritos, você melhora significativamente a legibilidade e a capacidade de manutenção de seus programas Python, tornando mais fácil para outras pessoas entender e trabalhar com seu código.

O que são comentários de várias linhas?

Os comentários multilinha do Python são úteis ao fornecer explicações ou notas mais extensas sobre seções de código específicas. Eles também são úteis quando você precisa desativar temporariamente várias linhas de código durante a depuração ou desenvolvimento sem precisar comentar cada linha individualmente.

Existem dois métodos para criar comentários multilinha em Python:

1. Usando aspas triplas

2. Usando um símbolo de hash com continuação

Usando aspas triplas

Uma maneira de criar comentários de várias linhas em Python é usando aspas triplas, que consistem em três aspas simples ou duplas consecutivas.

Quando um bloco de texto é colocado entre aspas triplas, o Python o interpreta como uma string e o desconsidera se não for atribuído a uma variável.

Essa técnica permite que você escreva comentários de várias linhas do Python ou strings de várias linhas que se estendem por várias linhas, aprimorando a legibilidade do seu código.

O código a seguir ajuda a explicar o uso de aspas triplas para um bloco de comentário de várias linhas no código Python :

'''
This is a multi-line comment
in Python using triple quotes.
'''
print("Hello World!")

O código acima produzirá apenas “Hello World!” pois a string de várias linhas com aspas triplas é ignorada pelo interpretador.

Usando um símbolo de hash com continuação de linha

Outra abordagem para criar comentários de várias linhas em Python envolve o uso de símbolos hash (#) no início de cada linha, juntamente com caracteres de continuação de linha () para manter a legibilidade.

O seguinte é um exemplo de como escrever comentários de várias linhas em Python:

# This is a multi-line comment in Python
# using hash symbols with line continuation.
# It spans multiple lines, but each line requires a hash symbol.
print("Hello World!")

No exemplo acima, apenas “Hello World!” também serão exibidos, pois as linhas que começam com um símbolo de hash são tratadas como comentários de várias linhas pelo interpretador.

O que são comentários embutidos?

Comentários embutidos em Python permitem que você forneça contexto ou explicações para linhas de código específicas. Esses tipos de comentários são colocados na mesma linha que a instrução de código, separados por uma marca de cerquilha (#).

Veja a seguir um exemplo de comentário embutido em Python:

x = 10  # This variable stores the value 10
y = x * 2  # Multiply x by 2 to get the value of y
print(y)  # Output the value of y

Os comentários embutidos devem ser usados ​​com moderação e somente quando necessários para explicar uma linha específica de código. Se o seu código exigir comentários embutidos extensos, considere tornar o próprio código mais claro e autoexplicativo usando nomes de variáveis ​​ou funções mais descritivos.

O que são Docstrings?

Docstrings servem como uma ferramenta valiosa para documentar seu código de forma eficaz. Eles ajudam você e outros desenvolvedores a compreender como seu código funciona e sua finalidade.

Ao incorporar docstrings em seus programas Python, você pode criar explicações claras, concisas e úteis que melhoram muito a legibilidade e a capacidade de manutenção de seu código.

Essa prática promove uma melhor colaboração e comunicação entre os desenvolvedores, melhorando a qualidade do software que você cria.

Existem três tipos de docstrings em Python, todos com a mesma sintaxe, mas diferentes casos de uso:

1. Documentação de função e método

2. Class Docstrings

3. Class Docstrings

Documentação de função e método

As docstrings de função e método descrevem o propósito, os argumentos, os valores de retorno e os efeitos colaterais de uma função ou método.

Veja a seguir um exemplo de docstrings de função e método:

def add(a, b):
    """Add two numbers and return the result."""
    return a + b

Essa docstring deve sempre fornecer uma descrição concisa e informativa da função.

Class Docstrings

As docstrings de classe explicam o propósito e o comportamento de uma classe em Python.

Veja a seguir um exemplo de uso de docstrings de classe para explicar o propósito e o comportamento de uma classe em Python.

class MyClass:
    """A simple class to demonstrate docstrings."""
    
    def __init__(self, x):
        self.x = x

A docstring deve fornecer uma visão geral da funcionalidade da classe, quaisquer atributos ou propriedades importantes que ela possa ter e como ela interage com outras classes ou funções em seu programa.

Módulo Docstrings

As docstrings do módulo devem ser colocadas no início de seus módulos Python ou arquivos de módulo, oferecendo uma visão geral abrangente do propósito do módulo e seu conteúdo.

Ao incluir uma documentação de módulo bem escrita, você permite que os desenvolvedores verifiquem rapidamente como seu módulo se encaixa na arquitetura geral de seu projeto e nas funcionalidades específicas que ele oferece.

Essa prática não apenas melhora a legibilidade e a capacidade de manutenção do seu código, mas também promove uma melhor colaboração e compreensão entre os membros da equipe que trabalham no mesmo projeto.

Veja a seguir um exemplo de uso de docstrings de módulo para associar documentação a arquivos Python:

"""
geometry.py

This module contains functions to calculate the area of various geometric shapes,
such as rectangles, circles, and triangles. The main functions provided are:

- rectangle_area(width, height)
- circle_area(radius)
- triangle_area(base, height)

Each function takes the respective dimensions as input and returns the calculated area.
"""

def rectangle_area(width, height):
    return width * height

def circle_area(radius):
    import math
    return math.pi * (radius ** 2)

def triangle_area(base, height):
    return 0.5 * base * height

# Rest of the code...

Os principais recursos do módulo e quaisquer variáveis, classes ou funções importantes que ele inclua.

Melhores práticas para escrever comentários

Ok, agora que você tem uma boa ideia sobre os diferentes tipos de comentários em Python e como usá-los, vamos ver algumas práticas recomendadas para manter um alto padrão de trabalho.

Clareza e Concisão

Ao escrever comentários em Python, é essencial encontrar um equilíbrio entre clareza e concisão. Procure expressar seus pensamentos de uma maneira que facilite a compreensão e, ao mesmo tempo, garanta que os comentários permaneçam breves e informativos.

Evite incluir informações desnecessárias para evitar que os comentários se tornem excessivamente longos e difíceis de manter, o que pode levar a confusão.

Um comentário bem elaborado deve se integrar facilmente ao seu código, aumentando a legibilidade e a capacidade de manutenção.

Evitando Comentários Óbvios

É importante evitar descrições óbvias ao escrever qualquer comentário em Python . Em vez de simplesmente reafirmar ou duplicar o que o código faz, concentre-se em oferecer percepções que podem não ser facilmente aparentes no próprio código.

Isso se aplica a escrever um comentário de uma única linha e também a comentários de várias linhas.

Para ilustrar isso, considere o seguinte exemplo, que contrasta um comentário óbvio com uma alternativa mais útil:

# Bad comment
x = x + 1  # Increment x by 1

# Good comment
x = x + 1  # Adjust x to account for the new user added

Atualizando comentários como alterações de código

À medida que o código evolui, mantenha os comentários do Python atualizados. Comentários desatualizados podem enganar e causar confusão. Ao fazer alterações significativas em seu código, ajuste os comentários do Python de acordo para preservar a legibilidade e a compreensão.

Procurando aprofundar seu conhecimento em Python, confira nossos extensos vídeos de Python abaixo.

Conclusão

Comentar seu código oferece vários benefícios, como auxiliar na compreensão, manutenção e servir como documentação valiosa para os colaboradores.

Para garantir comentários eficazes:

1. Mantenha os comentários concisos, relevantes e informativos.

2. Use um símbolo de cerquilha (#) seguido por um espaço para comentários de linha única.

3. Use aspas (“”””””) para escrever comentários de várias linhas

4. Empregue comentários embutidos e em bloco para obter contexto ou explicações.

5. Atualize os comentários à medida que o código evolui para manter a legibilidade.

6. Pratique a escrita de comentários ponderados para aprimorar as habilidades de programação.

Ao usar consistentemente comentários bem elaborados, você não apenas ajuda a si mesmo e aos outros, mas também eleva sua experiência em programação.

Além disso, prestando atenção à qualidade dos comentários e incorporando insights valiosos em seus comentários, você se tornará um programador mais eficaz, organizado e profissional, facilitando a colaboração com outras pessoas e a manutenção do seu código a longo prazo.