Como Comentar um Bloco de Código em Python

plaintext
Comments are one of the most useful tools when working with Python. They guide us through the logic, decisions, and purposes behind blocks of code without interfering with the execution. Comentários são ferramentas muito úteis ao trabalhar com Python. Eles 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. Comments help make the code more readable and maintainable and facilitate collaboration in a team setting. 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.

This tutorial will delve into two effective methods for commenting out multiple lines of code in Python, ensuring your code is well-documented and easily understandable. 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.

Why Are Block Comments in Python Important? Por que Comentários de Bloco são Importantes em Python?

Comments are often one of the first concepts you encounter in your Python learning journey. Eles são frequentemente um dos primeiros conceitos que você encontra em sua jornada de aprendizado em Python. They provide useful context over the intent behind a certain code snippet. Eles fornecem contexto útil sobre a intenção por trás de um determinado trecho de código. They offer clarity and context over why a script behaves as it does. Eles oferecem clareza e contexto sobre por que um script se comporta como faz. There are a variety of important reasons why you should always use comments in your scripts. Existem várias razões importantes para que você sempre use comentários em seus scripts. Here are four of them: Aqui estão quatro delas:

• Documentation: Documentação: Comments act as a form of documentation explaining the purpose of functions, classes, or blocks of code. Os comentários atuam como uma forma de documentação explicando o propósito de funções, classes ou blocos de código. This is especially useful for complex algorithms where the logic may not be immediately apparent. Isso é especialmente útil para algoritmos complexos onde a lógica pode não ser imediatamente aparente.
• Readability: Legibilidade: Well-commented code is easier to read and understand. Código bem comentado é mais fácil de ler e entender. This is crucial when you or others revisit the code after some time. Isso é crucial quando você ou outros voltam ao código após algum tempo.
• Debugging: Depuração: Temporarily commenting out sections of code is a common practice for isolating and identifying bugs. Comentar temporariamente seções de código é uma prática comum para isolar e identificar erros.
• Colaboração: No ambiente de equipe, as comentários tornam o código mais compartilhável e compreensível, facilitando uma colaboração mais fluida e revisões de código.

Uso de Comentários de Linha Simples em Python

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

1. Posição: Coloque o símbolo # no início da linha ou depois do 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: Depois do símbolo #, escreva seu comentário. Isto 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 simples explicando a próxima linha de código
print("Hello, world!")  # Isto imprime uma mensagem na tela

Método #1: Comentando usando vários comentários de linha simples #

O modo mais direto de comentar em Python é usando o símbolo #, que comentará tudo o que vier a seguir ele na 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 é executar 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 desativar ou explicar.
2. Comentar cada linha: Coloque um símbolo # no início de cada linha que você deseja comentar. Isso informa ao interpretador do Python para ignorar estas linhas durante a execução.

Veja 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 Triplas

Uma alternativa para comentar várias linhas é usar literais de strings triplamente citadas (”’ ”’ ou “”” “””). Embora não sejam comentários de bloco oficiais, esses literais de strings são frequentemente usados como tais, especialmente para comentários de múltiplas linhas ou docstrings. Para usar strings triplamente citadas, simplesmente coloque ”’ ou “”” antes e depois do bloco de código que você deseja comentar, como no exemplo a seguir:

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

Os literais de strings triplamente citadas 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)

Estes literais de strings triplamente citadas são chamados de docstrings — você pode ler mais sobre eles em nosso tutorial de docstrings.