Covil Do Dev

Comentários em Python

Aprenda a escrever comentários em Python seguindo as melhores práticas de escrita e organização para mantê-los simples, coesos e úteis.


Lindomar Rodrigues
Lindomar Rodrigues

Atualizado

Quando você estiver escrevendo códigos em Python tente sempre fazer de forma que seu conteúdo seja auto explicativo. Para isso você deve utilizar classes e funções de forma corretas e definir variáveis com nomes claros, que sejam significativos.

Mesmo seguindo essas boas práticas básicas em alguns momentos o inevitavelmente seu código pode levantar algumas dúvidas, é nesse momento que um comentário será bem-vindo.

Lembre-se que os comentários são feitos para você e/ou outros programadores lerem e interpretarem oque está acontecendo naquele trecho, portanto não terão efeito na execução do seu código.

Como fazer um comentário em Python?

Para fazer um comentário simples em Python basta colocar uma hashtag(#) antes do texto.

# Conteúdo do comentário

Tudo que aparecer após uma hashtag(#) será ignorado, porém, você pode colocar código na mesma linha(desde que antes de iniciar o comentário) que esse será executado.

nome_site = "Covil Do Dev"
adjetivo = "muito bom"

print(f"{nome_site} é {adjetivo}.") # Conteúdo do comentário

A execução do script acima terá a seguinte saída: “Covil Do Dev é muito bom.”, ou seja, o conteúdo do comentário foi ignorado, porém o comando antes da hashtag(#) rodou sem problemas.

Comentando múltiplas linhas

Em Python, diferentemente de outras linguagens, não temos uma forma nativa para fazer comentários com mais de uma linha.

Se você já programou em outras linguagens provavelmente irá estranhar não poder fazer algo semelhante ao mostrado abaixo em c.

/* 
Comentário
em
várias
linhas
*/

Mesmo não tendo isso ou algo semelhante em Python podemos atingir o mesmo efeito com múltiplas hashtags(#).

# Comentário
# em
# várias
# linhas

Outra forma de fazer isso seria com uma string de múltiplas linhas, colocando o conteúdo do comentário entre 3 aspas.

"""
Comentário
em
várias
linhas
"""

Mesmo que, na prática, seja o mesmo efeito de um comentário, ou seja, não terá interferência no fluxo do programa, isto tecnicamente não é um comentário e sim uma string não associada a uma variável.

Porque fazer comentários em Python?

Como dito antes, comentários não impactam diretamente na execução do código. Porque fazer comentários então?

Para você mesmo

Quando estamos programando as coisas parecem óbvias, após investir horas, dias e até meses em um projeto você provavelmente já sabe o que armazena cada uma das variáveis e o que faz cada uma das funções. Se você abandonar esse código hoje e só abri-lo novamente daqui a 3 anos, será que as coisas ainda serão tão claras?

Se você já teve que revisar um código seu de alguns anos atrás, com certeza irá entender esse tópico. Por mais que pareça óbvio o que uma variável armazena na hora que programamos, após algum tempo longe desse código isso deixa de ser uma verdade.

Portanto, mesmo que você programe sozinho, ou tenha uma equipe extremamente bem entrosada em que todos revisam o código um dos outros, ainda assim a memória irá falhar em algum momento.

Quando isso acontecer você irá se arrepender de não ter investido alguns minutos para redigir um comentário na hora que aquele trecho foi feito.

Facilitar a leitura

Quando se programa um código simples, pequeno e sozinho é simples saber o que cada parte do código faz, mas sabemos que essa não é a realidade em muitos casos. Às vezes você está alterando, adicionando ou corrigindo um arquivo que você nunca viu na vida, e nesses casos quanto mais dados você tiver sobre oque faz aquele trecho específico mais simples e rápido será seu trabalho.

Então toda vez que você estiver programando lembre-se disso, que outra pessoa uma hora irá ler seu código, e provavelmente ficará agradecida se tiver um comentário explicando alguns trechos que possa parecer confuso.

Obviamente não é necessário comentar todas as linhas, até porque se seu código está confuso ao ponto disso ser necessário colocar comentários deveria ser a menor das suas preocupações.

O Código deve ser auto-explicativo e legível por natureza e os comentários ser apenas uma ferramenta de uso esporádico para deixar as coisas ainda mais claras.

Melhores práticas para comentários em Python

Comentar um código quando isso for pertinente sempre será uma boa prática, no guia de estilo do Python(PEP 8) diz que uma linha deve ter no máximo 72 caracteres.

Por esse motivo muitas vezes o comentário deve ser algo sutil, apenas um fragmento de texto que irá fazer toda a diferença na hora de entender o que está acontecendo naquele ponto.

Caso em algum momento você precise de um pouco mais de espaço talvez seja um bom para declarar uma nova função(com um nome já bem auto explicativo) e adicionar um docstring.

No guia de estilo na parte sobre comentários também diz uma coisa muito importante para nós brasileiros(e qualquer outro povo que não seja nativo na língua inglesa).

Python coders from non-English speaking countries: please write your comments in English, unless you are 120% sure that the code will never be read by people who don't speak your language.

Que em tradução livre seria:

Programadores Python falantes de outras línguas que não seja o Inglês: Por favor escrevam comentários em Inglês, a não ser que você esteja 120% certo que seu código não será lido por alguém que não fala sua língua.

Nesse ponto penso que vale aplicar o bom senso, muitas vezes comentar o código em inglês será apenas mais um ponto de atrito para sua equipe, sem trazer nenhum benefício prático.

Se a empresa que você e sua equipe trabalha produz código que será visto por pessoas em outras partes do mundo, mesmo que os programadores estejam fisicamente e sejam nativos do Brasil, acho que comentar o código em inglês será necessário.

De qualquer forma é algo muito individual de cada equipe e cabe avaliar se o desempenho será afetado por essa escolha.

Descreva algo para ser feito no futuro

Muitas vezes percebemos alguma função que necessita ser feita ou melhorada, mas não é nada vital ou não é o seu objetivo no momento, nesses casos é interessante colocar uma “nota” para lembrar você ou outra pessoa da equipe que aquela é um lugar que merece um pouco de atenção.

Suponha que abaixo temos um código de centenas de linhas e estamos dentro de uma função que faz várias coisas e em algum momento aparece o seguinte:

dlt = (b ** 2) - 4 * a * c
if dlt < 0:
    return None
else:
    x1 = (-b + dlt ** (1 / 2)) / (2 * a)
    x2 = (-b - dlt ** (1 / 2)) / (2 * a)

    return (x1, x2)

Se você foi um bom aluno no ensino médio talvez tenha identificado do que se trata, porém, podemos deixar uma sugestão de melhoria no código com um comentário.

# TODO -> Criar uma função separada para o cálculo do Delta
# TODO -> Definir a variável com um nome mais significativo. EX: delta

dlt = (b ** 2) - 4 * a * c

if dlt < 0:
    x1, x2 = None, None
else:
    x1 = (-b + dlt ** (1 / 2)) / (2 * a)
    x2 = (-b - dlt ** (1 / 2)) / (2 * a)

    return (x1, x2)

TODO é utilizado como um padrão para esse estilo de comentário, significa literalmente PARA FAZER.

Comentários TODO são bem úteis e ajudam a deixar o código melhor a cada dia. Podem ser muito mais bem elaborados, às vezes é interessante adicionar até um pseudo código para facilitar que quem esteja lendo entenda realmente oque precisa ser feito.

Explique funções

Muitas vezes temos funções que são muito simples para terem uma docstring própria, porém, em simultâneo, abrem margem para uma possível interpretação errada.

Utilizaremos o exemplo anterior, caso alguém tenha aceitado a sugestão e feito a função separada, essa função solta talvez não seja tão fácil de ser identificada, em casos assim colocar um comentário simples no cabeçalho da função pode ser algo útil.

def calc_delta(a, b, c):
    # Calcula a discriminante de uma função(o delta).
    # Discriminante é a parte da fórmula de Bháskara que está sob a raiz quadrada.

    return (b ** 2) - 4 * a * c

Evite comentários inúteis

Às vezes com a melhor das intenções acabamos por comentar todo o código, e nesses casos acontecem algumas aberrações, desde comentários desnecessários, comentários que não explicam nada e até repetição desnecessária.

Olhe o exemplo abaixo de um comentário desnecessário.

CHAVE_DA_API = '123456789' # Define uma constante com a chave da API

Nesse caso já estamos utilizando letras maiúsculas na variável, que em Python é o padrão para uma constante, e, além disso, o nome da constante já é bem explicativo, então esse comentário só deixa o código bagunçado e atrapalha uma leitura rápida.

Outros exemplos semelhantes de comentários inúteis são comentários explicando os módulos que estão sendo importados ou explicando retornos de funções.

import random # Importa o módulo random

Outro tipo de comentário inútil é os casos de repetições, onde muitas vezes o código é reescrito como um comentário apenas traduzindo o nome da função.

import random  # Importa random


def gera_numero_aleatorio():
    numero = random.randint(0, 10)

    return numero  # Retorna número

Às vezes isso acontece em loops também, principalmente fazendo interação em uma lista ou dicionário com o for e o in.

numeros = [9, 4, 1, 6, 9, 2]

# Passa em cada número presente em números
for numero in numeros:
    print(numero ** 2)

Em ambos os casos são comentários que não ajudam em nada, apenas polui visualmente o código e diminui a velocidade de alguém que esteja fazendo uma leitura dinâmica.

Seja educado

Isso não é uma boa prática do Python, nem da programação, e sim da vida. Muitas vezes vemos comentários rudes em códigos, um exemplo são xingamentos bobos colocados em funções.

def alguma_funcao(a,b,c):
    # Essa po*** não funciona 
    ...

Às vezes são um pouco mais graves também, xingamentos com um alvo específico, que vem muitas vezes em conjunto com uma soberba e uma tom de superioridade.

def alguma_funcao(a,b,c):
    # Corrige essa me*** João, ou eu mesmo terei que fazer?
    ...

Conclusão

Fazer comentários de corretamente é algo que torna a vida de todos mais fácil, inclusive a vida de quem faz o comentário.

Sempre acreditamos que temos total domínio e sabemos todos os detalhes do nosso código, mas basta ficar uma semana sem contato e essa confiança toda acaba e você se arrepende profundamente de não ter gastado alguns minutos comentando o código.

Normalmente só notamos os comentários quando eles não estão presentes, então mude agora, toda vez que fizer algo que abra espaço para uma interpretação incorreta, faça um comentário. Uma boa prática que não se restringe a comentários, mas os inclui é: sempre que alterar um código o deixe mais organizado do que estava antes.

Obrigado por visitar o blog e por ler esse artigo, se tive qualquer dúvida, ideia ou sugestão, não hesite em entrar em contato pelo meu e-mail: lindomar@covildodev.com.br