Adicionar Comentários em Python

Introdução

Neste laboratório, você aprenderá a importância e a aplicação prática de comentários em Python. Comentários são essenciais para tornar seu código compreensível, o que é crucial para manutenção e colaboração. Você explorará diferentes tipos de comentários, incluindo comentários de linha única e de múltiplas linhas, e aprenderá a usá-los de forma eficaz para melhorar a legibilidade do código.

Compreender o Propósito dos Comentários

Comentários são anotações dentro do seu código que são ignoradas pelo interpretador Python, mas são valiosas para leitores humanos. Eles ajudam a explicar a lógica, o propósito do código e quaisquer detalhes não óbvios. Enquanto uma máquina executa o código, são os humanos que precisam lê-lo e mantê-lo. Bons hábitos de comentário são essenciais para escrever programas limpos e compreensíveis.

Vamos começar com um script simples sem nenhum comentário. No WebIDE, localize o arquivo purpose.py no explorador de arquivos no painel esquerdo e abra-o.

Adicione o seguinte código ao arquivo purpose.py:

x = 10
y = 20
z = x + y
print(z)

Salve o arquivo pressionando Ctrl + S.

Para executar o script, abra o terminal integrado no WebIDE navegando até o menu superior e selecionando Terminal -> New Terminal. O terminal será aberto na parte inferior da tela, e o caminho padrão é ~/project.

Execute o script rodando o seguinte comando no terminal:

python purpose.py

Você verá a saída do cálculo:

30

Este script é direto, mas em um programa maior, pode não ficar imediatamente claro o que x, y e z representam. Na próxima etapa, adicionaremos comentários para tornar este código mais fácil de entender.

Usar Comentários de Linha Única

Comentários de linha única são usados para notas curtas e explicativas. Em Python, um comentário de linha única começa com o símbolo de cerquilha (#). O interpretador ignora tudo na linha que segue o #. Estes comentários podem ser colocados em uma linha separada para descrever o código abaixo ou na mesma linha de uma instrução para explicá-la.

Vamos modificar o arquivo purpose.py para incluir comentários de linha única. Abra purpose.py no editor e atualize seu conteúdo para o seguinte:

## This script calculates the sum of two numbers

x = 10  ## Assign the integer 10 to variable x
y = 20  ## Assign the integer 20 to variable y
z = x + y  ## Calculate the sum of x and y
print(z) ## Print the final result to the console

Salve o arquivo (Ctrl + S) e execute-o novamente no terminal:

python purpose.py

A saída será a mesma de antes:

30

Como você pode ver, os comentários não alteraram o comportamento do programa. No entanto, o código agora é muito mais legível. O primeiro comentário explica o propósito geral do script, enquanto os comentários inline (na linha) esclarecem o papel de cada linha.

Usar Comentários de Múltiplas Linhas

Para explicações mais longas que abrangem várias linhas, você pode usar o formato de comentário de múltiplas linhas. Embora Python não tenha uma sintaxe específica para comentários de múltiplas linhas como algumas outras linguagens, você pode usar strings de múltiplas linhas para este propósito.

Uma string de múltiplas linhas é criada envolvendo o texto em aspas triplas, seja """...""" (duplas) ou '''...''' (simples). Se esta string de múltiplas linhas não for atribuída a uma variável, o interpretador Python a ignorará, tornando-a efetivamente um comentário. Esta é uma convenção comum para escrever comentários de bloco ou documentação de função (docstrings).

Encontre e abra o arquivo multiline.py no WebIDE. Adicione o seguinte código:

"""
This is a multi-line comment using triple double quotes.
This script demonstrates how to write comments that span
several lines to provide more detailed explanations.
"""

message = "Hello, Python learners!"
print(message)

Salve o arquivo e execute-o a partir do terminal:

python multiline.py

Você verá a seguinte saída:

Hello, Python learners!

O bloco de texto dentro das aspas triplas foi ignorado, e apenas a instrução print foi executada. Esta técnica é muito útil para fornecer descrições detalhadas no início de um arquivo ou antes de uma função complexa.

Usar Comentários de Declaração

Python também suporta comentários especiais conhecidos como comentários de declaração (declaration comments). Estes são processados pelo interpretador ou pelo sistema operacional para configurar como o script é executado. Dois exemplos comuns são o shebang e a declaração de codificação (encoding declaration).

1. Shebang (#!): A linha shebang é a primeira linha de um script. Ela informa a um sistema operacional do tipo Unix qual interpretador usar para executar o arquivo. Para um script Python 3, isso é tipicamente #!/usr/bin/python3. Isso permite que você execute o script como um executável autônomo.

2. Declaração de Codificação (Encoding Declaration): Este comentário informa ao interpretador Python qual codificação de caracteres usar para o arquivo fonte. É importante se o seu código contiver caracteres não-ASCII. A declaração padrão para UTF-8 é ## -*- coding: utf-8 -*-. Ela deve ser colocada na primeira ou segunda linha do arquivo.

Vamos criar um script que usa ambos. Abra o arquivo declaration.py no editor e adicione o seguinte código:

#!/usr/bin/python3
## -*- coding: utf-8 -*-

## This script demonstrates declaration comments and non-ASCII characters.
print("Hello, World!")
print("你好，世界！") ## A greeting in Chinese

Salve o arquivo. Antes de poder executar este script diretamente, você precisa torná-lo executável. No terminal, execute o comando chmod:

chmod +x declaration.py

Agora, você pode executar o script diretamente sem digitar python primeiro:

./declaration.py

A saída exibirá corretamente ambas as linhas de texto, incluindo os caracteres chineses:

Hello, World!
你好, 世界!

A linha shebang permitiu que o sistema encontrasse e usasse o interpretador Python 3, e a declaração de codificação garantiu que os caracteres não-ASCII fossem tratados corretamente.

Resumo

Neste laboratório, você aprendeu a adicionar comentários ao seu código Python. Você praticou o uso de comentários de linha única com # para notas breves, comentários de múltiplas linhas com """...""" para descrições mais longas e comentários de declaração especiais como o shebang e a declaração de codificação para configurar a execução do script. Ao comentar seu código de forma eficaz, você o torna mais legível, manutenível e mais fácil de ser compreendido por outras pessoas (e por seu eu futuro).