Em Python, os comentários são trechos de texto ignorados pelo interpretador, servindo exclusivamente para documentar e explicar o código. Eles são fundamentais para melhorar a legibilidade, facilitar a manutenção e alinhar o entendimento em equipes de desenvolvimento. A seguir, exploramos os diferentes tipos de comentários, as convenções da PEP 8 e as armadilhas comuns.

Tipos de Comentários em Python

Embora a linguagem não possua uma sintaxe dedicada exclusivamente para blocos de comentários multilinhas, ela oferece três abordagens principais para documentar o código.

1. Comentários de Linha Única

Utilizados para explicações rápidas, são iniciados pelo caractere #. Tudo o que vem após esse símbolo na mesma linha é desconsiderado pelo interpretador.

• Sintaxe: Iniciar a linha ou o final da linha com #.
• Convenção: A PEP 8 recomenda inserir um espaço após o # para melhor legibilidade.

# Calcula a área de um retângulo com base na largura e altura
largura = 5
altura = 8
area = largura * altura  # Multiplicação das dimensões para obter a área total

2. Blocos de Texto com Strings Multilinhas

Para textos mais longos que não servem como documentação oficial de módulos ou funções, desenvolvedores frequentemente utilizam strings delimitadas por três aspas (simples ou duplas). Se essa string não for atribuída a uma variável, o interpretador a ignora durante a execução.

'''
Este bloco descreve o fluxo de processamento de dados.
Etapa 1: Leitura do arquivo CSV.
Etapa 2: Limpeza de valores nulos.
Etapa 3: Exportação para o banco de dados.
'''

def processar_dados(caminho_arquivo):
    # Lógica de implementação
    pass

3. Docstrings (Strings de Documentação)

As docstrings são o padrão oficial para documentar módulos, classes e funções. Diferente dos blocos de texto comuns, elas são associadas ao atributo __doc__ do objeto e podem ser acessadas em tempo de execução ou por ferramentas de geração de documentação.

• Posicionamento: Devem ser a primeira instrução dentro do módulo, classe ou função.
• Formato: Utilizam três aspas duplas (""") por convenção.

"""
Módulo de conversão de temperaturas.
Fornece utilitários para transformar graus Celsius em Fahrenheit e Kelvin.
"""

class ConversorTemperatura:
    """
    Classe para realizar conversões de unidades térmicas.
    """
    
    def celsius_para_fahrenheit(self, celsius):
        """
        Converte uma temperatura de Celsius para Fahrenheit.
        
        Args:
            celsius (float): Temperatura em graus Celsius.
            
        Returns:
            float: Temperatura equivalente em Fahrenheit.
            
        Raises:
            TypeError: Se o valor fornecido não for numérico.
        """
        if not isinstance(celsius, (int, float)):
            raise TypeError("A temperatura deve ser um valor numérico.")
        return (celsius * 9/5) + 32

# Acessando a docstring programaticamente
print(ConversorTemperatura.celsius_para_fahrenheit.__doc__)

Boas Práticas e Convenções (PEP 8)

A eficácia de um comentário está na sua clareza e relevância. Escrever comentários em excesso ou desatualizados pode ser pior do que não ter nenhum.

Diretrizes de Formatação

• Idioma: Em projetos open-source ou equipes globais, prefira o inglês. Para projetos locais, o idioma nativo é aceitável, desde que a codificação do arquivo seja UTF-8.
• Espaçamento: Comentários de fim de linha devem ser separados do código por pelo menos dois espaços.
• Alinhamento: O recuo do comentário deve corresponder ao bloco de código que ele descreve.

Exemplo de formatação inadequada:

velocidade=100#velocidade inicial do veículo
#calcula a distância
def calcular_distancia(t):
'''distância = velocidade * tempo
retorna o valor'''
    return velocidade * t

Exemplo de formatação correta:

velocidade = 100  # Velocidade inicial do veículo em km/h

# Calcula a distância percorrida com base no tempo
def calcular_distancia(tempo):
    """Calcula a distância utilizando a fórmula de movimento uniforme."""
    return velocidade * tempo

Diretrizes de Conteúdo

• Evite o óbvio: Não explique o que o código faz se a sintaxe já for clara (ex: contador += 1 # Incrementa o contador).
• Foque no "porquê": Explique a motivação por trás de uma decisão técnica, especialmente em lógicas complexas ou workarounds.
• Mantenha atualizado: Um comentário que contradiz o código é extremamente prejudicial. Atualize-os sempre que refatorar a lógica.

def buscar_usuario(id_usuario):
    """
    Recupera os dados essenciais do usuário no banco de dados.
    
    Nota: A consulta foi otimizada para buscar apenas campos escalares,
    ignorando o campo 'historico_compras' para evitar sobrecarga de memória
    em listas de usuários muito grandes.
    """
    id_numerico = int(id_usuario) if isinstance(id_usuario, str) else id_usuario
    return repositorio.obter_usuario_por_id(id_numerico)

Armadilhas Comuns e Como Evitá-las

Uso Incorreto de Strings Multilinhas

Utilizar strings de três aspas no meio de uma função, sem atribuí-las a uma variável ou sem serem a primeira instrução, não as transforma em comentários oficiais. O interpretador as avalia como expressões de string descartáveis, o que pode gerar overhead desnecessário e confusão.

def executar_tarefa():
    print("Iniciando...")
    '''
    Este texto não é uma docstring.
    É apenas uma string literal que será criada e descartada na memória.
    '''
    print("Concluído.")

Para desativar blocos de código temporariamente durante testes, utilize o atalho de comentário de linha única da sua IDE (geralmente Ctrl+/ ou Cmd+/), que insere # em cada linha selecionada.

Problemas de Codificação de Caracteres

Embora o Python 3 utilize UTF-8 como padrão, ambientes legados ou configurações específicas de eidtores podem forçar outras codificações (como Latin-1 ou Windows-1252). Isso resulta em erros de sintaxe ao utilizar caracteres acentuados nos comentários. Para garantir a compatibilidade universal, declare a codificação no topo do arquivo:

# -*- coding: utf-8 -*-

Inconsistência em Docstrings

Misturar diferentes estilos de documentação (como reStructuredText, Google e NumPy) no mesmo projeto dificulta a leitura e quebra a geração automática de documentação. Adote um padrão único, sendo o estilo Google amplamente recomendado por sua excelente legibilidade tanto em código-fonte quanto em renderizações HTML.