Python / Sintaxe / Comentários

Em Python, um comentário começa com # fora de uma string e termina no fim da linha. Para comentar várias linhas, coloque # em cada uma. Aspas triplas criam uma string, eventualmente usada como docstring, e não constituem uma sintaxe de comentário.

Comentários de linha e # dentro de strings

Comentários comuns explicam intenções e condições do código; seu conteúdo é ignorado durante a análise sintática. Eles podem ocupar a linha inteira ou aparecer depois de uma instrução. Consulte as regras oficiais dos comentários em Python para conhecer seu alcance.

Os exemplos exigem apenas Python 3. Salve cada exemplo completo em comments_example.py com UTF-8 e execute python comments_example.py, ou python3 conforme sua instalação. Substitua o conteúdo do arquivo para testar os demais exemplos de forma independente.

# Calculate the total before discounts.
price = 100
quantity = 2  # Number of items
print(price * quantity)

Resultado esperado:

200

Dentro de aspas, # faz parte do texto. Por isso não corta uma frase nem o fragmento de uma URL:

print("# This is part of a string")
print("https://example.com/page#section")

# This is part of a string
https://example.com/page#section

Marcar cada linha de uma explicação longa

Python não oferece uma sintaxe separada de comentário de bloco como /* ... */ em C. Comente cada linha e alinhe a indentação com o código descrito para deixar clara a relação.

# The sample uses a fixed discount rate.
# Production rules may depend on the customer.
base_price = 100
discount_rate = 0.1
print(base_price * (1 - discount_rate))

90.0

Para desativar código temporariamente, comente suas linhas; para reativá-lo, remova as marcas. Editores normalmente automatizam essa operação com um comando de comentário de várias linhas. Guarde implementações antigas no histórico de versões, em vez de acumular alternativas comentadas no arquivo.

Aspas triplas e docstrings são strings

Três aspas simples ou duplas delimitam um literal de string que pode ocupar várias linhas. Quando é a primeira instrução de um módulo, classe ou função, esse literal torna-se uma docstring, acessível por __doc__ e ferramentas de ajuda. Veja a explicação oficial sobre docstrings.

def greet(name):
    """Return a greeting for name."""
    return f"Hello, {name}"

print(greet("Ada"))
print(greet.__doc__)

Hello, Ada
Return a greeting for name.

Esse valor documenta a função e pode ser consultado, ao contrário de um comentário explicativo comum. A mesma notação também permite armazenar dados reais:

notes = """first line
second line"""
print(notes.splitlines())

['first line', 'second line']

Envolver código arbitrário em aspas triplas não o transforma em comentário verdadeiro. Aspas iguais no conteúdo podem quebrar a sintaxe, e a posição pode fazê-lo ser interpretado como docstring. Para desativar linhas, use #.

Um bloco só com comentários precisa de uma instrução

Blocos de def, if e construções semelhantes precisam de uma instrução real. Comentários não contam, portanto um bloco apenas comentado pode causar IndentationError. A instrução pass, que não realiza nenhuma ação, funciona como espaço reservado.

source = "def todo():\n    # Implement later\n"
try:
    compile(source, "example", "exec")
except IndentationError:
    print("IndentationError")

def todo():
    # Implement later
    pass

print(todo())

IndentationError
None

A primeira parte compila código inválido guardado em uma string e captura o erro para permitir que o exemplo continue. A função posterior é válida por conter pass. Sem um retorno explícito, sua chamada devolve None.

Explicações úteis e diretivas especiais

PEP significa Python Enhancement Proposal. As recomendações da PEP 8 para comentários alertam para comentários que contradizem o código. Explique decisões, restrições externas e condições importantes em vez de repetir ações óbvias, e atualize os comentários quando o código mudar. Um comentário no fim da linha normalmente usa pelo menos dois espaços antes de # e um depois.

Alguns comentários têm significado para ferramentas ou para a leitura do arquivo. Uma declaração de codificação válida na primeira ou segunda linha pode afetar sua interpretação; Python 3 usa UTF-8 por padrão. Diferencie diretivas de linters e verificadores de tipos das explicações comuns e investigue os avisos antes de ocultá-los indiscriminadamente.