Em momentos como o que vivemos agora, é de se esperar que a partir do ócio de ficar em casa surja criatividade. Bom, não foi o meu caso nesses últimos dias.

Para a escrita deste artigo, inicialmente pensei em falar sobre o funcionamento do tempo de execução do JavaScript, um tema muito importante para qualquer desenvolvedor web. Entretanto, já existem muitos materiais de qualidade sobre isso, tanto em inglês quanto em português, como a palestra do Philip Roberts na JSConf EU, em que ele destrincha o funcionamento do Event Loop.

Além disso, também cheguei a estudar containers e suas propriedades, conhecendo experts na área como a Julia Evans, que oferta materiais incríveis sobre o tema. De qualquer forma, não foi dessa vez em que escrevi um tutorial sobre eles e tecnologias auxiliares, como Docker e Kubernetes.

Já faz um tempo que tenho vontade de escrever sobre algo não tão técnico, mas sim algo que passa despercebido e é importante em nosso cotidiano. Foi quando encontrei uma palestra da Sarah Drasner que fez tudo se encaixar para que essa redação fosse escrita. Sendo assim, nessa edição vamos fugir do formato tradicional do PET Redação e discutir um pouco sobre comentários, gatekeeping, viés de sobrevivência e outras coisas.

Comentários são falhos! Ou será que não?

Desde o início da jornada da maioria dos desenvolvedores de software, somos ensinados sobre o quão importante são os comentários em nosso trabalho. Até mesmo para os mais incrédulos, basta ter que trabalhar em projetos com código legado ou revisitar projetos antigos para entender a importância dos comentários. Mas ao contrário do que se aprende no início de nossas carreiras, há um tipo de lógica muito presente na cabeça de muitos desenvolvedores que já estão inseridos no mercado de trabalho: comentários são ruins.

Quem nunca ouviu a seguinte frase: “Você não precisa de comentários se escrever um código limpo”? Muito provavelmente a popularidade dessa ideia se disseminou com o livro Código Limpo¹. Nesse livro, há um capítulo dedicado especificamente aos comentários, mas que aborda eles como um mal necessário, iniciando imediatamente com a citação abaixo.

“Não comente código ruim, reescreva-o”

Brian W. Kernighan and P. J. Plaugher

O autor do livro explica que comentários são essencialmente falhos, porque sua existência já demonstra que o programador falhou em se expressar através do código. Junto disso, também ressalta que o código de uma aplicação se transforma, é apagado, reescrito e assim em diante, e o comentário não o segue nessa evolução. Ele afirma que os programadores poderiam ser disciplinados a atualizar os comentários conforme a progressão do código, mas que o melhor a se fazer é dispender essa energia totalmente à escrita de um código legível.

Todos os pontos levantados por ele podem ser válidos, mas ocorre um equívoco em seu raciocínio. Não importa o quão bem escrito e limpo seja o seu código, há uma limitação:

“Código pode explicar como, mas não pode explicar por quê”

Sarah Drasner

        Em sua palestra sobre a Arte dos Comentários, Sarah Drasner² demonstra que há uma limitação linguística de todas as linguagens de programação: elas não foram feitas exclusivamente para comunicação entre seres humanos. Observemos este exemplo: qual dos dois trechos de códigos abaixo é mais legível?

        A resposta certa seria: depende.  Não há como afirmar que há um consenso do que é um código legível para todos, já que somos todos pessoas com opiniões e experiências diferentes. Um código que é limpo para nós hoje pode se tornar um código confuso daqui a 5 anos. Sendo assim, não há por que abolir comentários da programação assim como não devemos usá-los como muleta para escrever códigos confusos e ruins, mas tratá-los como uma ferramenta que precisava ser revisada e atualizada assim como qualquer código.

Os comentários podem ser bons!

        Podemos destacar vários tipos de comentários que são, sim, importantes e até mesmo necessários em vários momentos, podendo ser temporários ou até mesmo permanentes. Algumas das situações que podemos utilizar os comentários são as seguintes:     

• Entendendo o porquê de um código: comentários conseguem transmitir explicações que não podem ser inferidas pela estrutura de uma função, como o porquê de se utilizar funcionalidade X e não funcionalidade Y;
• Legibilidade: as linguagens de programação não foram escritas para comunicação entre seres humanos, então é muito difícil identificar o que certos códigos significam, como um código de compatibilidade para navegadores antigos;
• Separação do código em seções: uma técnica útil para auxiliar desenvolvedores a localizarem áreas de responsabilidade dentro de um código, deixando claro onde se localiza o código responsável pelo cálculo X e onde fica a função que realiza a análise desse cálculo, por exemplo;

        No entanto, não se prenda a esses exemplos como um guia. Um comentário pode ser usado sempre que preciso, desde que ele não piore a experiência de desenvolver naquela base de código, sendo que cada caso precisa ser analisado separadamente. Portanto, não há problema em remover comentários que ajudam inicialmente mas acabam sendo inúteis posteriormente: eles também podem ter validade!

E às vezes podem ser bem ruins…

        Ainda assim, há casos em que o comentário realmente nunca deveria ter sido escrito, geralmente por ser um tempo e energia gastos pelo desenvolvedor que não geram valor para a base de código, como os seguintes exemplos:

• Reescrevendo o que o código significa: MUITOS comentários servem somente para explicar o que está acontecendo em uma escala pequena, como a definição de variáveis, mas não precisamos disso. O significado daquela linha está contido dentro daquela declaração;
• Comentários ultrapassados: comentários que não são mantidos junto ao código acabam confundindo mais os desenvolvedores, como quando a  informação em um comentário não se relaciona de forma alguma com a declaração abaixo;
• Comentários utilizados para guardar códigos antigos: esse item é auto explicativo. Usar comentários dessa forma para testes rápidos é aceitável, mas mantê-los em seu projeto é ruim para a legibilidade. Há muitas maneiras de salvar versões antigas de funcionalidades em um código, principalmente com a existência de ferramentas de versionamento, como o Git.

        Vale lembrar que eles também não devem ser usados como muletas ao escrever códigos ruins, porque temos que tentar ser o mais legíveis possíveis em nossas ideias. De qualquer forma, exceções acontecem e deadlines apertadíssimas muitas vezes irão exigir que medidas desesperadas sejam tomadas.

Faça o seu melhor!

Independente de todos os exemplos dados aqui, não há um guia oficial ou um consciente coletivo sobre como usar os comentários. Não existe isso de nunca escrever comentários, ou sempre comentar, mas devemos, sim, assumir uma postura de utilizá-los de uma forma racional e que agregue valor ao nosso trabalho.

Ao comentar uma linha de código, sempre se coloque no lugar de quem escreve mas também de quem lerá aquele comentário, pensando sempre sobre que tipo de informação é necessária para que você seja o mais produtivo possível. Sempre faça o seu melhor.

Algumas coisas precisam mudar

Antes de finalizar o artigo, vale ressaltar que boa parte dessas ideias contrárias à realização de comentários e outras atividades que não são classicamente tarefas de “desenvolvedor raiz”, se disseminam através de dois tipos de eventos que ocorrem muito dentro da área de Tecnologia da Informação: gatekeeping e viés de sobrevivência.

Explicando ambos de forma simples, gatekeeping é a atividade em que um indivíduo toma para si a função de dizer se outro indivíduo faz parte de um grupo ou comunidade. Enquanto isso, viés de sobrevivência faz com que nos concentremos somente em indivíduos ou coisas que passaram por algum tipo de seleção, ignorando os que não sobreviveram a esse processo.

Na área de desenvolvimento de software, principalmente quando se trata de desenvolvimento desktop e back-end, muitas ideias e costumes acabam sendo replicados através do viés de sobrevivência, já que os processos e ferramentas são ultrapassados por muitos sistemas serem antigos. Entenda o que quero dizer: desenvolvedores mais velhos e mentores assumem que a maneira certa de se programar é passando pelas mesmas dificuldades que levaram eles ao ponto em que chegaram. Dessa forma, não importa se o seu conceito de código limpo é diferente do resto, você DEVE adaptar-se à norma! Esse processo acaba por prejudicar e até mesmo afastar muitos desenvolvedores da profissão, principalmente membros de minorias, como mulheres, não brancos e queers, por exemplo.

Também, medidas de juízo de valor são frequentes utilizadas em várias comunidades de software, não sendo incomum que desenvolvedores apegados à processos relacionados às soft skills ou até mesmo front-end, como o estudo e uso de comentários de uma maneira eficiente, acabem sendo rebaixados ou até mesmo excluídos.

Esse tipo de comportamento é tóxico e precisa ser abolido de qualquer ambiente de desenvolvimento em que exista. Antes de programadores, somos seres humanos com histórias, contextos e vidas diferentes. Ninguém passou por uma linha de montagem para chegar até onde estamos, então não vamos exigir uma igualdade injusta mas , sim, equidade.

¹ Para quem não o conhece, o livro é escrito por Robert “Uncle Bob” Cecil Martin, uma personalidade muito influente no ambiente de desenvolvimento. Ele é um dos 17 signatários originais do Manifesto Ágil, atualmente prestando consultoria internacionalmente e tendo escrito muitos livros na área de desenvolvimento de software.

² Esse artigo foi muito inspirado na incrível palestra realizada pela Sarah Drasner na JSConf Hawai’i, então não deixem de assisti-lá nesse link. Para saber mais sobre a Sarah e seu trabalho, acesse esse seu website.

Referências:

• The Art of Code Comments – Sarah Drasner | JSConf Hawaii 2020
• Stop Writing Code Comments
• Programming – Commenting
• Putting comments in code: the good, the bad, and the ugly.
• How to Comment Your Code Like a Pro: Best Practices and Good Habits
• Clean Code: A Handbook of Agile Software Craftsmanship