Como comentar um bloco de código em Python

Os comentários são uma das ferramentas mais úteis ao trabalhar com Python. Eles nos orientam sobre a lógica, as decisões e os objetivos por trás dos blocos de código sem interferir na execução. Os comentários ajudam a tornar o código mais legível e passível de manutenção, além de facilitar a colaboração em um ambiente de equipe.

Este tutorial abordará dois métodos eficazes para comentar várias linhas de código em Python, garantindo que seu código seja bem documentado e facilmente compreensível.

Por que os comentários em bloco são importantes em Python?

Os comentários costumam ser um dos primeiros conceitos que você encontra em sua jornada de aprendizado do Python. Eles fornecem um contexto útil sobre a intenção por trás de um determinado trecho de código. Eles oferecem clareza e contexto sobre o motivo pelo qual um script se comporta dessa forma. Há vários motivos importantes pelos quais você deve sempre usar comentários em seus scripts. Aqui estão quatro deles:

• Documentação: Os comentários funcionam como uma forma de documentação que explica a finalidade de funções, classes ou blocos de código. Isso é especialmente útil para algoritmos complexos em que a lógica pode não ser imediatamente aparente.
• Legibilidade: Um código bem comentado é mais fácil de ler e entender. Isso é fundamental quando você ou outras pessoas revisam o código depois de 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, os comentários tornam o código mais compartilhável e compreensível, facilitando a colaboração e as revisões de código.

Uso de comentários de bloco de linha única em Python

Antes de nos aprofundarmos no comentário de várias linhas, vamos começar com os conceitos básicos dos comentários de linha única. Em Python, um comentário de uma única linha começa com o símbolo de hash (#), e o interpretador Python ignora tudo o que vem em seguida nessa linha. Para criar um comentário de linha única, siga as instruções abaixo:

1. Colocaçã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 de forma independente.
2. Conteúdo: Após o símbolo #, escreva seu comentário. Isso pode ser uma explicação da linha de código, uma nota para referência futura ou qualquer informação útil relacionada ao código.

# This is a single-line comment explaining the next line of code
print("Hello, world!")  # This prints a message to the console

Método nº 1: Comentário usando várias linhas simples #

A maneira mais direta de comentar em Python é usar o símbolo #, que comenta tudo o que vem depois dele na linha. Embora o Python não tenha uma sintaxe específica para comentários em bloco, você pode usar vários símbolos # para comentar cada linha individualmente. Tudo o que você precisa fazer é executar as seguintes etapas:

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

Você pode ver o exemplo abaixo:

# Example of commenting out multiple lines individually 
# def example_function(name):
#	# This function prints "Hello " and the input name
# 	print("Hello", name)

Método de comentário de bloco Python nº 2: Comentários usando literais de cadeia de caracteres com aspas triplas

Um método alternativo para comentar várias linhas é usar literais de cadeia de caracteres entre aspas triplas ('''' ''' ou """ """). Embora não sejam oficialmente comentários de bloco, esses literais de cadeia de caracteres são frequentemente usados como tal, especialmente para comentários de várias linhas ou docstrings. Para usar cadeias de caracteres com aspas triplas, basta colocar ''' ou """ antes e depois do bloco de código que você deseja comentar, da seguinte forma:

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

Os literais de string entre aspas triplas são mais comumente usados para documentar funções Python. Por exemplo:

# Create 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"
	'''
	# Print the output 
	print("Hello", name)

Esses literais de string com aspas triplas são chamados de docstrings - você pode ler mais sobre eles em nosso tutorial sobre docstrings.

Considerações finais

Os comentários são uma parte indispensável da escrita de código Python limpo, sustentável e colaborativo. Não importa se você está usando comentários de uma linha com # ou comentários de várias linhas com strings entre aspas triplas, o objetivo é melhorar a legibilidade e a compreensão do seu código.

Para ler mais e aprofundar seu conhecimento sobre as práticas recomendadas de programação em Python, confira os seguintes recursos:

• Pista de habilidades de fundamentos de Python
• 6 práticas recomendadas de Python para um código melhor
• Documentando o código Python: Guia de como fazer