Criando Comentários no Python da Forma Correta

Comentários são notas que os programadores postam no código para explicar o que o código deve fazer. Comentários são ignorados por compiladores ou interpretadores que transformam código em ações, mas podem ser essenciais no gerenciamento de um projeto de software.

Os comentários ajudam a explicar seu código Python para outros programadores, mas eles também podem ser úteis para você lembrar porque você fez certas escolhas. Os comentários facilitam a depuração e a revisão de código, ajudando futuros programadores a entender as escolhas de projeto por trás do software.

Embora os comentários sejam principalmente para os desenvolvedores, escrever comentários eficazes também pode ajudar na produção de excelente documentação para os usuários do seu código. Com a ajuda de geradores de documentos como o Sphinx para projetos Python, comentários em seu código podem fornecer conteúdo para sua documentação.

Vamos dar uma olhada nos comentários no Python.

Comentários no Python

Conforme o Guia de Estilo Python PEP 8, há várias coisas para se ter em mente ao escrever comentários:

• Os comentários devem ser sempre frases completas e concisas.
• É melhor não ter nenhum comentário do que um que seja difícil de entender ou impreciso.
• Os comentários devem ser atualizados regularmente para refletir as mudanças no seu código.
• Muitos comentários podem distrair e reduzir a qualidade do código. Comentários não são necessários onde o propósito do código é óbvio.

Em Python, uma linha é declarada como um comentário quando começa com o símbolo #. Quando o intérprete Python encontra # em seu código, ele ignora qualquer coisa depois daquele símbolo e não produz nenhum erro. Há duas maneiras de declarar comentários de uma linha: comentários em linha e comentários em bloco.

Comentários em linha

Os comentários em linha fornecem pequenas descrições de variáveis e operações simples sendo escritos na mesma linha da declaração do código:

border = x + 10  # Make offset of 10px

O comentário explica a função do código na mesma declaração que o código.

Comentários em bloco

Comentários em bloco são usados para descrever lógica complexa no código. Os comentários de bloco no Python são construídos de forma similar aos comentários em linha – a única diferença é que os comentários de bloco são escritos em uma linha separada:

import csv
from itertools import groupby

# Get a list of names in a sequence from the csv file
with open('new-top-firstNames.csv') as f:
    file_csv = csv.reader(f)

# Skip the header part: (sr, name, perc)
header = next(file_csv)
    
# Only name from (number, name, perc)
persons = [ x[1] for x in file_csv]

# Sort the list by first letter because 
# The groupby function looks for sequential data.
persons.sort(key=lambda x:x[0])
data = groupby(persons, key=lambda x:x[0])

# Get every name as a list 
data_grouped = {}
for k, v in data:
    # Get data in the form 
    # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]}
    data_grouped[k] = list(v)

Note que ao usar comentários em bloco, os comentários são escritos acima do código que eles estão explicando. O Python PEP8 Style Guide dita que uma linha de código não deve conter mais de setenta e nove caracteres, e os comentários em linha muitas vezes movem as linhas por esse comprimento. É por isso que os comentários em bloco são escritos para descrever o código em linhas separadas.

Comentários em várias linhas

Python não suporta nativamente comentários de várias linhas, o que significa que não há nenhuma provisão especial para defini-los. Apesar disso, comentários que abrangem várias linhas são frequentemente usados.

Você pode criar um comentário com várias linhas a partir de vários comentários de uma linha, prefixando cada linha com #:

# interpreter 
# ignores
# these lines

Você também pode usar a sintaxe de strings de caracteres de várias linhas. Em Python, você pode definir strings de caracteres com várias linhas, anexando em """, aspas duplas triplas, ou ''', aspas simples triplas:

print("Multi-Line Comment")
"""
This
String is 
Multi line 
"""

No código acima, a string de múltiplas linhas não é atribuída a uma variável, o que faz com que a string funcione como um comentário. Em tempo de execução, Python ignora a string, e ela não está incluída no bytecode. A execução do código acima produz a seguinte saída:

Multi-Line Comment

Comentários especiais

Além de tornar seu código legível, os comentários também servem alguns propósitos especiais em Python, tais como planejar futuras adições de código e gerar documentação.

Comentários no Python Docstring

Em Python, docstrings são comentários de várias linhas que explicam como usar uma determinada função ou classe. A documentação do seu código é melhorada com a criação de docstrings de alta qualidade. Ao trabalhar com uma função ou classe e usar a função help(obj) integrada, a docstrings pode ser útil para dar uma visão geral do objeto.

Python PEP 257 fornece um método padrão de declaração de documentos em Python, mostrado abaixo:

from collections import namedtuple
Person = namedtuple('Person', ['name', 'age'])

 def get_person(name, age, d=False):
    """
Returns a namedtuple("name", "age") object.
Also returns dict('name', 'age') if arg `d` is True

Arguments:
name  – first name, must be string
age   – age of person, must be int
d     – to return Person as `dict` (default=False)

"""
p = Person(name, age)
if d:
    return p._asdict()
return p

No código acima, a docstring forneceu detalhes sobre como a função associada funciona. Com geradores de documentação como o Sphinx, esta docstring pode ser usada para dar aos usuários do seu projeto uma visão geral de como usar este método.

Um docstring definido logo abaixo da função ou assinatura de classe também pode ser retornado usando a função help(). A função help() toma um objeto ou nome de função como argumento, e retorna as docstrings da função como saída. No exemplo acima, help(get_person) pode ser chamado para revelar as docstrings associadas à função get_person. Se você executar o código acima em uma shell interativa usando a flag -i, você pode ver como este docstring será analisado pelo Python. Execute o código acima digitando python -i file.py.

A chamada de função help(get_person) retorna um docstring para à sua função. A saída contém get_person(name, age, d=False), que é uma assinatura de função que o Python adiciona automaticamente.

O atributo get_person.__ doc__ também pode ser usado para recuperar e modificar docstrings programmaticamente. Após adicionar “Mais algumas informações novas” no exemplo acima, ele aparece na segunda chamada para help(get_person). Ainda assim, é improvável que você precise alterar a docstrings dinamicamente em tempo de execução como este.

Comentários TODO

Ao escrever código, há ocasiões em que você vai querer destacar certas linhas ou blocos inteiros para melhorar. Estas tarefas são marcadas pelos comentários do TODO. Comentários TODO são úteis quando você está planejando atualizações ou mudanças no seu código, ou se você deseja informar aos usuários ou colaboradores do projeto que seções específicas do código do arquivo ainda estão para ser escritas.

Os comentários TODO não devem ser escritos como pseudocódigo – eles apenas têm que explicar brevemente a função do código ainda não escrito.

Comentários TODO e comentários de bloco de uma linha são muito semelhantes, e a única distinção entre eles é que os comentários TODO devem começar com um prefixo TODO:

# TODO Get serialized data from the CSV file
# TODO Perform calculations on the data
# TODO Return to the user

É importante notar que embora muitas IDEs possam destacar estes comentários para o programador, o intérprete Python não vê os comentários TODO de forma diferente dos comentários de bloco.

Melhores práticas ao escrever comentários no Python

Há uma série de melhores práticas que devem ser seguidas ao escrever comentários para garantir confiabilidade e qualidade. Abaixo estão algumas dicas para escrever comentários de alta qualidade em Python.

Evite o óbvio

Comentários que afirmam o óbvio, não agregam nenhum valor ao seu código, e devem ser evitados. Por exemplo:

x = x + 4 # increase x by 4

Esse comentário não é útil, já que simplesmente declara o que o código faz sem explicar porque ele precisa ser feito. Os comentários devem explicar o “por que” ao invés do “o quê” do código que eles estão descrevendo.

Reescrito de forma mais útil, o exemplo acima pode se parecer com este:

x = x + 4 # increase the border width

Mantenha os comentários curtos

Mantenha seus comentários curtos e de fácil compreensão. Eles devem ser escritos em prosa padrão, não em pseudo-código, e devem substituir a necessidade de ler o código real para obter uma visão geral do que ele faz. Demasiados detalhes ou comentários complexos não facilitam o trabalho de um programador. Por exemplo:

# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r)
def get_area(r,h):
    return (2*3.14*r*h) + (2*3.14*r*r)

O comentário acima fornece mais informações do que as necessárias para o leitor. Ao invés de especificar a lógica central, os comentários devem fornecer um resumo geral do código. Este comentário pode ser reescrito como:

# return area of cylinder
def get_area(r,h):
    return (2*3.14*r*h) + (2*3.14*r*r)

Use Identifiers cuidadosamente

Os Identifiers devem ser usados cuidadosamente nos comentários. Mudar nomes de Identifiers ou casos pode confundir o leitor. Exemplo:

# return class() after modifying argument
def func(cls, arg):
    return cls(arg+5)

O comentário acima menciona class e argument, nenhum dos quais é encontrado no código. Este comentário pode ser reescrito como:

# return cls() after modifying arg
def func(cls, arg):
    return cls(arg+5)

DRY e WET

Quando você está escrevendo código, você quer aderir ao princípio DRY (não se repita) e evitar WET (escreva tudo duas vezes).

Isso também se aplica aos comentários. Evite usar múltiplas declarações para descrever seu código e tente fundir comentários que expliquem o mesmo código em um único comentário. Entretanto, é importante ter cuidado quando você estiver mesclando comentários: a fusão descuidada de múltiplos comentários pode resultar em um enorme comentário que viola os guias de estilo e é difícil para o leitor acompanhar.

Lembre-se que os comentários devem reduzir o tempo de leitura do código.

"># function to do x work
def do_something(y):
    # x work cannot be done if y is greater than max_limit
    if y < 400:
      print('doing x work')

No código acima, os comentários são desnecessariamente fragmentados, e podem ser fundidos em um único comentário:

"># function to do x if arg:y is less than max_limit
def  do_something(y):
    if y in range(400):
        print('doing x work')

Indentação Consistente

Certifique-se de que os comentários sejam indentados no mesmo nível do código que eles estão descrevendo. Quando não estão, eles podem ser difíceis de seguir.

Por exemplo, este comentário não é indentado ou posicionado corretamente:

for i in range(2,20, 2):
# only even numbers
    if verify(i):
# i should be verified by verify()
        perform(x)

Ela pode ser reescrita da seguinte forma:

# only even numbers
for i in range(2,20, 2):
    # i should be verified by verify()
    if verify(i):
        perform(x)

Resumo

Os comentários são um componente importante para escrever um código compreensível. O investimento que você faz ao escrever um comentário é um investimento que seu futuro eu – ou outros desenvolvedores que precisam trabalhar na sua base de código – irá apreciar. Comentar também permite que você obtenha insights mais detalhados sobre o seu código.

Neste tutorial, você aprendeu mais sobre os comentários no Python, incluindo os vários tipos de comentários Python, quando usar cada um deles, e as melhores práticas a seguir ao criá-los.

Escrever bons comentários é uma habilidade que precisa ser estudada e desenvolvida. Para praticar a escrita de comentários, considere voltar atrás e adicionar comentários a alguns de seus projetos anteriores. Para inspiração e para ver as melhores práticas em ação, confira os projetos bem documentados Python no GitHub.

Quando você estiver pronto para fazer seus próprios projetos Python em tempo real, a plataforma Hospedagem de Aplicativos da Kinsta pode levar seu código do GitHub para a nuvem em segundos.

Vivek Singh

Vivek é um desenvolvedor Python e Django que está sempre pronto para aprender e ensinar coisas novas aos colegas desenvolvedores.