Crie Comentários em Python da Maneira Certa

Comentários são notas que os programadores adicionam ao seu código para explicar o que esse código deve fazer. Os compiladores ou interpretadores que transformam o código em ação ignoram os comentários, mas podem ser essenciais para o gerenciamento de projetos de software.

Os comentários ajudam a explicar seu código Python para outros programadores e podem lembrá-lo de por que você fez as escolhas que fez. Os comentários facilitam a depuração e a revisão do código, ajudando futuros programadores a entender as opções de design por trás do software.

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

Vamos olhar sob o capô de comentários em Python.

Comentários em Python

De acordo com o Python PEP 8 Style Guide, há várias coisas a serem lembradas 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 alterações em 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 comentário quando começa com o símbolo # . Quando o interpretador Python encontra # em seu código, ele ignora qualquer coisa após esse símbolo e não produz nenhum erro. Há duas maneiras de declarar comentários de linha única: comentários embutidos e comentários em bloco.

Comentários embutidos

Os comentários embutidos fornecem descrições curtas de variáveis ​​e operações simples e são escritos na mesma linha que a instrução de código:

 border = x + 10 # Make offset of 10px

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

Bloquear comentários

Comentários de bloco são usados ​​para descrever lógica complexa no código. Os comentários de bloco em Python são construídos de forma semelhante aos comentários inline — 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)

Observe que, ao usar comentários de bloco, os comentários são escritos acima do código que estão explicando. O Python PEP8 Style Guide determina que uma linha de código não deve conter mais de setenta e nove caracteres, e os comentários embutidos geralmente empurram as linhas além desse comprimento. É por isso que os comentários em bloco são escritos para descrever o código em linhas separadas.

Comentários de várias linhas

O Python não oferece suporte nativo a comentários de várias linhas, o que significa que não há provisão especial para defini-los. Apesar disso, comentários abrangendo várias linhas são frequentemente usados.

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

 # interpreter # ignores # these lines

Você também pode usar a sintaxe de strings de várias linhas. Em Python, você pode definir strings de várias linhas colocando-as entre """ , aspas duplas triplas ou ''' , aspas simples triplas:

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

No código acima, a string de várias linhas não é atribuída a uma variável, o que faz com que a string funcione como um comentário. No tempo de execução, o Python ignora a string e não é 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 a alguns propósitos especiais em Python, como planejar futuras adições de código e gerar documentação.

Comentários 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 é aprimorada pela criação de docstrings de alta qualidade. Ao trabalhar com uma função ou classe e usar a função interna help(obj) , as docstrings podem ser úteis para fornecer uma visão geral do objeto.

Python PEP 257 fornece um método padrão de declaração de docstrings 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 fornece 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.

Uma docstring definida logo abaixo da assinatura da função ou da classe também pode ser retornada usando a função integrada help() . A função help() recebe um nome de objeto ou 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 docstrings associadas à função get_person . Se você executar o código acima em um shell interativo usando o sinalizador -i , poderá ver como essa docstring será analisada pelo Python. Execute o código acima digitando python -i file.py .

A chamada de função help(get_person) retorna uma 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 programaticamente. Depois de 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 dinamicamente docstrings em tempo de execução como este.

TODO Comentários

Ao escrever código, há ocasiões em que você deseja destacar certas linhas ou blocos inteiros para melhorias. Essas tarefas são marcadas por comentários TODO. Os comentários TODO são úteis quando você planeja atualizações ou alterações em seu código, ou se deseja informar aos usuários ou colaboradores do projeto que seções específicas do código do arquivo ainda precisam ser escritas.

Os comentários TODO não devem ser escritos como pseudocódigo - eles apenas precisam explicar brevemente a função do código ainda não escrito.

Os comentários TODO e os comentários em bloco de linha única são muito semelhantes, e a única diferença 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 observar que, embora muitos IDEs possam destacar esses comentários para o programador, o interpretador Python não vê os comentários TODO de maneira diferente dos comentários em bloco.

Melhores práticas ao escrever comentários em Python

Há uma série de práticas recomendadas 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 valor ao seu código e devem ser evitados. Por exemplo:

 x = x + 4 # increase x by 4

Esse comentário não é útil, pois simplesmente declara o que o código faz sem explicar por que precisa ser feito. Os comentários devem explicar o “porquê” em vez do “o quê” do código que estão descrevendo.

Reescrito de forma mais útil, o exemplo acima pode ser assim:

 x = x + 4 # increase the border width

Mantenha os comentários do Python curtos e agradáveis

Mantenha seus comentários curtos e de fácil compreensão. Eles devem ser escritos em prosa padrão, não em pseudocódigo, e devem substituir a necessidade de ler o código real para obter uma visão geral do que ele faz. Muitos detalhes ou comentários complexos não facilitam o trabalho do 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 o necessário para o leitor. Em vez de especificar a lógica principal, 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 identificadores com cuidado

Os identificadores devem ser usados ​​com cuidado nos comentários. Alterar nomes de identificadores 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)

SECO e MOLHADO

Ao escrever código, você deve seguir o princípio DRY (não se repita) e evitar WET (escrever tudo duas vezes).

Isso também é verdade para comentários. Evite usar várias instruções para descrever seu código e tente mesclar os comentários que explicam o mesmo código em um único comentário. No entanto, é importante ter cuidado ao mesclar comentários: a mesclagem descuidada de vários comentários pode resultar em um comentário enorme que viola os guias de estilo e é difícil para o leitor seguir.

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 fragmentados desnecessariamente e podem ser mesclados 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')

Recuo Consistente

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

Por exemplo, este comentário não está recuado 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 da escrita de código compreensível. O investimento que você faz ao escrever um comentário é algo que seu futuro eu — ou outros desenvolvedores que precisam trabalhar em sua base de código — apreciarão. Comentar também permite que você obtenha insights mais profundos sobre seu código.

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

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

Quando você estiver pronto para criar seus próprios projetos Python, a plataforma de hospedagem de aplicativos da Kinsta pode levar seu código do GitHub para a nuvem em segundos.