Sem comentários

By | June 28, 2020

Uma coisa que a gente aprende na escola ou universidade quando começa um curso de programação é: “Coloque comentários no seu código”.

Isso normalmente é tão mal-ensinado que você acaba achando por aí coisas desse tipo:

x = x + 1 # adiciona 1 a variavel x

Parabéns, você poluiu seu código com informação inútil e acabou fazendo ele pior do que o original.

Longe de mim dizer que sou um programador experiente, mas depois de ter a oportunidade de trabalhar em código realmente bom em alguns empregos e de ler livros excelentes eu percebi um padrão: Código bom não precisa de comentários.

Minha maior experiência é com Python então vou dar exemplos usando essa linguagem.

Nomes de variáveis

Os nomes das variáveis devem ser claros e refletir o conteúdo delas o melhor possível:

x += 1 # Errado
total_clients += 1 # Certo

Nomes de funções

Além de serem claras, não devem mentir sobre o estão fazendo:

def get_user_information(user):  # Errado
    if user in get_system_users():
        return True
    return False

def is_system_user(user):  # Certo
    if user in get_system_users():
        return True
    return False

Tamanho de funções

Uma coisa que gera a necessidade de comentários no código é o tamanho de métodos e funções. É tanta coisa numa única função que começa a ficar confuso. Muitas condicionais e loops, tratamento de casos especias, exceções, breaks, parse de texto…

Do livro Clean Code:

The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that. Functions should not be 100 lines long. Functions should hardly ever be 20 lines long.

Ou numa tradução livre: “A primeira regra sobre funções é que elas devem ser pequenas. A segunda regra é que devem se menor do que isso. Funções não devem ter 100 linhas. Funções mal devem chegar a 20 linhas.

Recentemente fiz refactoring num programa lá na empresa. Tinha sido criado por um estagiário com mais ou menos umas 300~350 linhas.

Era praticamente inescrutável. Demorei semanas escrevendo testes primeiro pra entender o que estava acontecendo e também pra ter certeza que não ia estragar nada. Eram só umas 3 ou 4 funções, algumas passando de 100 linhas. Que dor de cabeça.

Quebrei tudo em partes menores e cresceu pra umas 500 linhas, mas muito mais fácil de ler e entender o que estava acontecendo. E removi muitos cometários no processo.

Docstring não é comentário

Vale a pena dizer aqui que docstring não é comentário. Você deve utilizar de docstrings e provavelmente é tudo que você precisa colocar no seu código, desde que siga as regras acima.

Mas Docstring não são necessárias

Em muitos casos você pode nem precisar de Docstring. Python3 agora tem suporte a Type Hints e fica fácil documentar a assinatura da sua função.

Antes:

def get_user_id(user):
""" 
Get the numeric id for the user.
 Args: user (str) - The username
 Returns: int - The numeric id
"""
... (código)

Agora:

def get_user_id(user: str) -> int:
... (código)

Quando adicionar comentários

Lógico que vão ter situações onde comentários são necessários. Normalmente você precisa colocar alguns quando precisar explicar porquê está fazendo alguma coisa. Não como está fazendo.

Um exemplo de um código meu:

# If we are in a dev/test branch this will fail,
# so wrapping into a try block.
try:
 ... codigo que não falharia em produção
except Exception:
  pass

Outra coisa que invariavelmente vale a pena comentar são expressões regulares. Coloque um comentário explicando o que a expressão está procurando, talvez até um link pra documentação externa. Não tem nada pior que tentar decifrar regex de coleguinha!

Minha opinião pode sempre mudar, mas o que acredito no momento é que se você precisa colocar muito comentário no seu código isso provavelmente significa que ele não está claro o bastante para uma pessoa inexperiente na linguagem entender.

Li esses dias numa tradução livre algo mais ou menos assim “Qualquer idiota consegue escrever código que um computador entende. Difícil mesmo é escrever código que pessoas entendam“.

Mantenha isso em mente quando estiver programando. 😜

No tag for this post.