Comentários em Python — Linha Única, Múltiplas Linhas e Boas Práticas

Comentários são linhas no seu código-fonte que o interpretador Python ignora completamente. Eles existem para leitores humanos — para explicar a intenção, documentar decisões e sinalizar problemas — sem afetar como o programa é executado. Este capítulo aborda todos os tipos de comentários em Python, quando usar cada um e as convenções que mantêm grandes bases de código legíveis.

Comentários de linha única

Um comentário de linha única começa com o caractere cerquilha (#). Tudo a partir do # até o final dessa linha é ignorado pelo interpretador.

# Calculate the area of a circle
radius = 5
area = 3.14159 * radius ** 2
print(area)  # outputs 78.53975

O comentário na última linha — colocado após o código executável na mesma linha — é chamado de comentário inline. Use-os com moderação; reserve-os para lógica genuinamente não óbvia, em vez de repetir o que o código já diz.

Quando usar comentários de linha única

• Explique o porquê de uma decisão ser tomada, não o que o código faz (o código mostra o quê).
• Marque soluções temporárias: # TODO: replace with database lookup.
• Desative uma única linha temporariamente durante a depuração.

# FIXME: division by zero if user_count is 0
average = total_score / user_count

Comentários de múltiplas linhas

Python não tem uma sintaxe de comentário multilinha dedicada como C tem /* ... */. A forma idiomática de abranger várias linhas é usar comentários de linha única consecutivos, cada um começando com #.

# This function converts a temperature in Celsius to Fahrenheit.
# The formula is: F = (C * 9/5) + 32
# Returns a float rounded to two decimal places.
def celsius_to_fahrenheit(c):
    return round((c * 9 / 5) + 32, 2)

print(celsius_to_fahrenheit(100))  # 212.0
print(celsius_to_fahrenheit(0))    # 32.0

A maioria dos editores e IDEs Python permite selecionar várias linhas e alternar # em todas elas de uma vez (geralmente Ctrl+/ ou Cmd+/).

Docstrings — comentários de documentação estruturada

Python tem uma convenção especial de literal de string chamada docstring (abreviação de documentation string). Uma docstring é uma string com aspas triplas colocada imediatamente após um cabeçalho def, class ou module. Embora tecnicamente seja uma expressão de string, não um comentário, ela serve como o mecanismo de documentação padrão e é acessível em tempo de execução por meio do atributo __doc__.

def greet(name):
    """Return a personalised greeting message.

    Args:
        name (str): The name of the person to greet.

    Returns:
        str: A greeting string.
    """
    return f"Hello, {name}!"

print(greet("Alice"))        # Hello, Alice!
print(greet.__doc__)         # prints the docstring above

Strings com aspas triplas como comentários de bloco

Como Python descarta literais de string que não são atribuídos a nada, uma string com aspas triplas sozinha (que não esteja em uma posição def/class) é às vezes usada como um comentário de bloco informal:

"""
This script processes the daily sales report.
It reads from sales.csv, aggregates by region,
and writes a summary to report.txt.
"""

import csv

Esse padrão funciona, mas tem um custo sutil: ao contrário dos comentários com #, o interpretador analisa a string e pode mantê-la no bytecode compilado. Para documentação em nível de módulo, prefira uma docstring de módulo adequada (a primeira instrução no arquivo). Para outras explicações multilinha dentro de funções, use linhas consecutivas com #.

Comentando código durante a depuração

Desativar código temporariamente com comentários é uma técnica comum de depuração:

def calculate_discount(price, rate):
    # discount = price * rate        # old flat-rate formula
    discount = price * rate if rate < 1 else price * (rate / 100)
    return price - discount

print(calculate_discount(100, 0.2))   # 80.0
print(calculate_discount(100, 20))    # 80.0

Depois de confirmar a correção, remova as linhas comentadas em vez de deixá-las na base de código permanentemente — código comentado obsoleto confunde leitores futuros.

Diretivas especiais de comentários

Python e suas ferramentas reconhecem algumas linhas de comentários que têm significado legível por máquina:

A linha shebang

Em sistemas do tipo Unix, a primeira linha de um script pode especificar o interpretador:

#!/usr/bin/env python3
# This line tells the OS to run the file with python3.

print("Hello from a standalone script!")

Essa linha é um comentário no que diz respeito ao Python (começa com #), mas o sistema operacional a usa quando o arquivo é executado diretamente (./script.py).

Declaração de codificação

Se o seu arquivo-fonte usar uma codificação de caracteres diferente de UTF-8 (o padrão desde o Python 3), declare-a na primeira ou segunda linha:

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

O Python 3 usa UTF-8 por padrão, então isso raramente é necessário hoje em dia, mas você pode encontrá-lo em código legado.

Diretivas de verificador de tipos

Verificadores de tipos como mypy respeitam comentários inline especiais:

x = []  # type: ignore
result = some_function()  # type: ignore[return-value]

Eles suprimem erros de tipo específicos sem alterar o comportamento em tempo de execução. Veja o capítulo Variáveis Python para mais informações sobre como Python lida com tipos.

Boas práticas de comentários

Seguir essas convenções tornará seus comentários genuinamente úteis:

O PEP 8 — o guia de estilo oficial do Python — recomenda:

• Comentários inline devem ser separados da instrução por pelo menos dois espaços.
• Cada comentário inline deve começar com # (cerquilha, depois um espaço).
• Comentários de bloco que se aplicam ao código abaixo deles devem ser indentados no mesmo nível.

def apply_tax(price, tax_rate):
    # Tax rate is expressed as a decimal (e.g., 0.07 for 7 %).
    # Prices must be non-negative; validation happens upstream.
    tax = price * tax_rate
    return price + tax  # total including tax

Erros comuns a evitar

1. Deixar comentários TODO sem rastreá-los

# TODO: handle the case where the file does not exist
data = open("data.txt").read()

TODOs são úteis durante o desenvolvimento, mas devem ser vinculados a um rastreador de problemas, não deixados indefinidamente no código de produção.

2. Comentar grandes blocos em vez de excluí-los

O controle de versão (git) preserva o histórico. Não há necessidade de manter código comentado para a posteridade — exclua-o e dependa do git log se precisar dele de volta.

3. Estilo inconsistente

Uma mistura de #comment, # comment e ## comment no mesmo arquivo faz a base de código parecer sem dono. Concorde com um estilo e aplique-o de forma consistente.

Resumo

Comentários são uma ferramenta leve que traz benefícios sempre que outro desenvolvedor (ou você no futuro) lê seu código. Para leituras mais aprofundadas sobre tópicos relacionados, veja Sintaxe Python e Variáveis Python.

Prática