Como comentar um bloco de código em Python

Comentários são uma das ferramentas mais úteis ao trabalhar com Python. Guiam-nos através da lógica, decisões e propósitos por trás de blocos de código sem interferir na execução. Os comentários ajudam a tornar o código mais legível e manutenível e facilitam a colaboração em um ambiente de equipe.

Este tutorial irá explorar dois métodos eficazes para comentar várias linhas de código em Python, garantindo que seu código esteja bem documentado e de fácil compreensão.

Por que Comentários de Bloco em Python são Importantes?

Comentários são frequentemente um dos primeiros conceitos que você encontra em sua viagem de aprendizado em Python. Eles fornecem contexto útil sobre a intenção por trás de um determinado trecho de código. Oferecem clareza e contexto sobre por que um script se comporta como faz. Existem várias razões importantes para que você sempre use comentários em seus scripts. Aqui estão quatro delas:

• Documentação: Comentários atuam como uma forma de documentação explicando o propósito de funções, classes ou blocos de código. Isso é especialmente útil para algoritmos complexos onde a lógica pode não ser imediatamente aparente.
• Legibilidade: Código bem comentado é mais fácil de ler e entender. Isso é crucial quando você ou outros retornam ao código após algum tempo.
• Depuração: Comentar temporariamente seções de código é uma prática comum para isolar e identificar bugs.
• Colaboração: Em um ambiente de equipe, comentários tornam o código mais partilhável e compreensível, facilitando uma melhor colaboração e revisão do código.

Uso de Comentários de Bloco de Linha Única em Python

Antes de nós mergulharmos em comentar várias linhas, vamos começar com os fundamentos dos comentários de linha única. Em Python, um comentário de linha única começa com o símbolo de hash (#), e o interpretador Python ignora tudo o que vem a seguir naquela linha. Para criar um comentário de linha única, siga as instruções abaixo:

1. Localização: Coloque o símbolo # no início da linha ou após o código na mesma linha. Os comentários podem ser colocados acima do código que descrevem, na mesma linha à direita do código, ou isolados.
2. Conteúdo: Após o símbolo #, escreva seu comentário. Isso pode ser uma explicação da próxima linha de código, uma nota para referência futura ou qualquer informação útil relacionada ao código.

# Este é um comentário de linha única explicando a próxima linha de código
print("Hello, world!")  # Isto imprime uma mensagem na consola

Método #1: Comentando Usando Vários Comentários de Linha Única #

O modo mais direto de comentar em Python é usando o símbolo #, que comentará tudo o que vier a seguir na mesma linha. Embora o Python não tenha uma sintaxe específica para comentários de bloco, você pode usar vários símbolos # para comentar cada linha individualmente. Tudo o que você precisa fazer é seguir os seguintes passos:

1. Identificar o bloco de código: Primeiro, identifique o bloco de código que você deseja comentar. Isso pode ser uma função, um loop, ou qualquer segmento do seu código que você queira desabilitar ou explicar.
2. Comentar cada linha: Coloque um símbolo # no início de cada linha que você deseja comentar. Isso diz ao interpretador do Python para ignorar essas linhas durante a execução.

Você pode ver o exemplo abaixo:

# Exemplo de comentário de várias linhas individualmente
# def exemplo_function(nome):
#	# Esta função imprime "Hello " e o nome de entrada
# 	print("Hello", nome)

Método de Comentário de Bloco em Python #2: Comentando Usando Literais de String com Aspas Triplicadas

Um método alternativo para comentar várias linhas é usar literais de string tripla (”’ ”’ ou “”” “””). Embora não sejam comentários de bloco oficiais, esses literais de string são frequentemente usados como tais, especialmente para comentários de múltiplas linhas ou docstrings. Para usar strings triplas, simplesmente coloque ”’ ou “”” antes e depois do bloco de código que você deseja comentar, como é feito:

'''
def example_function(name):
	print("Hello", name)
'''

Literais de string tripla são usados principalmente para documentar funções em Python. Por exemplo:

# Crie example_function()
def example_function(name):
	'''
	This function takes as input a name, and returns a salutation to the name in the form of "Hello name"
	'''
	# Imprima a saída
	print("Hello", name)

esses literais de string tripla são chamados de docstrings – você pode saber mais sobre eles em nosso tutorial de docstrings.