Finalmente começo a comentar alguns dos capítulos do “Código Limpo” mais a fundo contando minhas experiências a respeito. O termo “experiência” aqui é o mais adequado pois vou falar sobre os efeitos que vi do capítulo 4 (“Comentários”) do livro em pessoas com quem trabalhei, projetos nos quais atuei e histórias que chegaram a mim.

O termo “Nefasto” também foi bem pensado: na minha experiência este é um dos textos que mais problemas trouxe para a nossa área.

A ideia essencial por trás deste capítulo é que os comentários são um mal necessário e que só existem por que não conseguimos nos expressar de forma clara através do nosso código. Com o tempo as pessoas foram percebendo que esta é na realidade uma ideia muito ruim, inclusive seus mais ardorosos defensores criaram um novo termo: “comentários estratégicos”.

Então neste post vou primeiro analisar como o texto é escrito e depois apresentar minhas próprias ideias sobre o tema baseadas em outros autores que li e minhas próprias experiências.

Alguns avisos

Aqui falo sobre a tradução do livro “Clean Code” para o português feito pela editora Alta Books. Para esta análise não levo em consideração o texto original.

Esta terceira parte é fundamentada no que apresento nas duas primeiras desta série nas quais analiso o modo como o texto é escrito e como, acredito, este gera comportamentos exageradamente exaltados em parte dos seus leitores. Caso não as tenha lido e se interesse, seguem os links:

• Parte 1 – Catequização
• Parte 2 – Descompilando

Não se exalte nos comentários deste blog. Ele é meu, pessoal, e bloqueio quem eu quiser. Todos são bem vindos para discutir, mas ninguém é obrigado a ler tratados e comentários agressivos aqui.

Tal como nos outros textos não quero estar certo, mas levantar uma discussão para que seja possível termos uma leitura mais crítica e rica do texto e crescer neste assunto.

Este não é um texto sobre política (mas toca no tema (contraditório hein? (é))).

Em 2000 eu trabalhava em uma livraria…

Com 21 anos tive meu primeiro emprego que achava realmente “sério”: trabalhava como vendedor (“livreiro”) na Livraria da Travessa em Belo Horizonte, que era focada em livros da área de Ciências Humanas. Foi um período importantíssimo para minha formação pois tive contato com diversos autores que me forjaram e alguns que me enganaram.

Dentre os autores que me enganaram havia um em especial que me seduziu inicialmente pelo comportamento dos seus leitores. Eles chegavam a mim desconfiados, falando baixo, olhando para os lados com medo de serem vistos pedindo seus livros. Diziam que era alguém com opiniões muito fortes e que tecia críticas ferozes aos intelectuais e mídia da época.

(eu sempre achava que estes leitores iam me pedir algum livro pornográfico e ficava decepcionado depois quando descobria o que realmente queriam…)

Eu tinha 21 anos, não sabia nada da vida (ainda não sei) e alguém que xingava só podia ser coisa boa. Li alguns dos seus textos naquela época e o achei realmente brilhante. Era cativante por que o modo como criticava o mundo me fazia sentir que eu era parte de um grupo seleto que agora via as coisas “como realmente eram”.

No ano seguinte entrei para o curso de Filosofia e tive contato com outros autores, foi quando resolvi reler o tal autor de forma mais atenta e fiquei chocado com a quantidade de bobagens e absurdos que este dizia de forma tão sedutora. Era absurdo: escrevia sobre Aristóteles, por exemplo, como se fosse um expert, mas nunca o havia lido no original (neste caso é necessário), relativizava escravidão e, no final das contas era só um infeliz cuja escrita exteriorizava suas próprias frustrações e alimentava o ressentimento alheio.

(Quem não tem frustrações? Quem não se sente confortado ao ver alguém atacando a fonte de nossos ressentimentos?)

E esta sensação de desconstrução da genialidade (aka “perceber que era uma grande bobagem que havia me iludido”) que tive ao ler atentamente este autor e a postura de diversos dos seus leitores que se mostraram pessoas fanatizadas com o tempo (“catequizadores”) me lembram muito a minha experiência com o texto do capítulo “Comentários”. O autor a que me refiro foi o Olavo de Carvalho.

Minha primeira impressão sobre este capítulo foi tão positiva que em 2016 escrevi neste blog sobre o assunto e ao final recomendava este texto. Duvida? Aqui o link.

A ideia de que eu só escrevia comentários por que meu código não era claro o suficiente foi por um tempo inclusive um incentivo para que eu escrevesse código mais fácil de ser mantido. Entretanto com o tempo ficou claro que a questão era bem mais profunda e muito mais rica.

Um aviso sobre olavo de carvalho

Apesar de ter comparado Robert Martin a Olavo de Carvalho este texto não é sobre Olavo de Carvalho.

As similaridades acabam nos pontos que mencionei (a constatação de que o capítulo sobre Comentários não era genial, mas tóxico e parte dos seus leitores que se tornaram catequizadores). Robert Martin não tem um passado tão terrível quanto carvalho, nem disseminou desinformação (até onde sei) durante a pandemia, o que pode ter causado a morte de pessoas (no caso do Brasil, muita gente).

Robert Martin deixará um legado positivo, ao contrário de carvalho (mesmo tendo escrito este capítulo sobre o qual escrevo).

(e eu não vou aceitar comentários sobre carvalho neste blog (é meu, aceito o que quiser aqui))

De qual Código Limpo estou falando?

Tal como disse no primeiro post da série há claramente duas versões do livro: a oficial e a não oficial. A segunda diz respeito aos comentários e diversas interpretações ao texto que, neste caso, mudam bastante o significado do que está na versão oficial.

Aqui falo da versão oficial e, tal como dito na introdução, da tradução para o português feita pela editora Alta Books. Mas vou contar mais adiante uma história que me aconteceu relativa à versão “alternativa” do livro.

Construção do argumento

O início do capítulo é o momento em que o autor nos seduz para concordarmos com seu argumento usando as estratégias que já vimos nas primeiras duas partes: metáforas morais, expressões controversas e um claro apelo à emoção.

Logo no início o leitor será induzido a ter uma percepção negativa sobre comentários e isto fica bem claro nas citações que trago abaixo, presentes logo no começo do capítulo:

“Nada pode ser tão prejudicial quanto um velho comentário mal feito que dissemina mentiras e informações incorretas”

Robert C. Martin – primeiro parágrafo do capítulo – já começa com metáforas morais

“Comentários não são como a Lista de Schindler. Não são o “bom puro”. De fato, eles são, no máximo, um mal necessário.”

Robert C. Martin – segundo parágrafo do capítulo – (aqui se vê problemas na tradução inclusive). Observe o apelo á emoção na referência ao filme.

“O uso adequado de comentários é compensar nosso fracasso em nos expressar no código”

Robert C. Martin – terceiro parágrafo do capítulo – (discordo muito sobre isto e falarei mais adiante) (de novo, repare que tradução ruim na colocação dos termos)

“Por que eu não gosto de comentários? Porque eles mentem“

Robert C. Martin – quinto parágrafo do texto. Atenção para o uso de metáfora moral tal como aponto na segunda parte desta série.

Mesmo quando vai falar sobre quando comentários são positivos, o autor nos solta um…

“Tenha em mente, contudo, que o único comentário verdadeiramente bom é aquele em que você encontrou uma forma para não escrevê-lo”

Robert C. Martin – primeiro parágrafo da seção “Comentários Bons” do capítulo. Novamente, atenção para a má tradução da seção e até mesmo o mal gosto da expressão usada pelo autor.

Na sequência o autor vai expor o que considera serem comentários válidos: observe que interessante.

• Informações legais – comentários sobre licença de uso, por exemplo.
• Comentários informativos (no texto é propositalmente vago o que ele chama de “comentários informativos”).
• Explicitação da intenção (a maior parte dos comentários na realidade é a explicitação da intenção).
• Esclarecimentos.
• Alertas sobre consequências.
• TODOs.
• Destaques.

Observe que são tipos de comentários realmente super válidos, mas sabe o que é interessante? Na tradução para o português é gasto o dobro de páginas para falar sobre comentários ruins.

É interessante observar a linguagem adotada pelo autor na descrição dos comentários ruins: é muito parecida com aquela adotada por pessoas que agridem seus colegas (normalmente iniciantes) em seus code reviews. Vamos a um exemplo:

Às vezes você vê comentários que nada são além de “chiados”. Eles dizem o óbvio e não fornecem novas informações:

/**
Default constructor
*/
protected AnnualDateRule() {
}
Ah, sério? Ou este:
/** Dia do mês */
private int dayOfMonth;

Robert C. Martin – Capítulo 4 – Seção comentários ruidosos. Grifo do autor.

Consigo imaginar um leitor neste momento me questionando: “Kico, sério? Isto aí que você está falando é mimimi!!!” (detesto a expressão “mimimi”). Respondo: sério. Na minha experiência um dos maiores danos que você pode causar a quem está iniciando é justamente este tipo de linguagem em um code review.

Mas aqui há uma razão para tal: faz parte da estratégia do autor de conquistar o leitor pela rabugice e ridicularização tóxica de erros muito comuns por quem está começando (o que gera a sensação de pertencimento a um grupo seleto de seus leitores). Há personagens que usam a mesma estratégia para conquistar o espectador: Dr. House, Chefe Ramsay, juízes cruéis de reality shows, Steve Jobs…

(a glamorização do babaca)

Se você já tem muitos anos de experiência, tal como eu, talvez tenha se esquecido que quando começou os comentários muito provavelmente eram o que te ajudavam a ter segurança nos seus primeiros códigos. Atacar esta “muleta” do iniciante da forma como é feito neste livro é um desfavor.

E aí consigo imaginar o leitor me questionando de novo: “então como posso abordar o tema dos comentários com um novato, Kico?“. Respondo: tal como Steve McConnell faz no seu livro “Code Complete”. Ele mostra como alguns comentários podem ser ruins, mas não os ridiculariza e nem usa metáforas morais para te convencer disto, usa apenas fatos.

E sabe onde Steve McConnell fala sobre comentários? No capítulo 32: “Self Documented Code”, que é essencialmente o que Robert Martin tenta fazer neste capítulo nefasto. Sabe o que é ainda mais interessante? Este capítulo está na segunda edição do Code Complete, publicada em 2004. A primeira edição de Clean Code é de 2008. Robert Martin não cita Code Complete neste capítulo.

(A primeira edição de Code Complete é publicada em 1993 e foi um livro bastante influente. É importante ter esta informação histórica aqui neste parêntese (que é um comentário))

E esta é a argumentação básica de Robert C. Martin neste capítulo. Sabe o que é mais triste? Ele termina o capítulo mostrando como refatorar comentários ao final, mas não diz o que seria intelectualmente honesto aqui para informar o leitor no decorrer de sua argumentação: comentários não são eternos e são alterados conforme o código muda no decorrer do tempo.

Em 2016 eu já estava na itexto…

Oferecemos um tipo de consultoria chamado “suporte de aquisição” na qual intermediamos quem adquire serviços de desenvolvimento e quem presta estes serviços. O objetivo não é policiar ou fiscalizar,mas sim ajudar as duas pontas evitando conflitos e reduzindo custos: com isto detecto possíveis problemas no que está sendo construído antes que ele chegue ao cliente e, ao mesmo tempo, ajudo o cliente a entender o que de fato está comprando.

(e, claro, ajudo os fornecedores a não perderem seus clientes)

Em um dos nossos primeiros casos lidei com a aquisição de uma plataforma enorme. Era um projeto que já estava terminando o primeiro ano de desenvolvimento e estava atrasado em pelo menos três meses. Ainda pior: a equipe interna de desenvolvedores do cliente não conseguia absorver o trabalho contratado pois não havia documentação sobre a arquitetura do projeto.

Conversando com o fornecedor ouvi algo que mudou minha visão inicialmente positiva do capítulo “Comentários” do Clean Code:

“Nós não documentamos nossa plataforma por que seguimos os princípios ágeis pregados pelo Clean Code, segundo o qual o código já se auto explica.”

Vindo da liderança técnica da equipe

Meu trabalho inicial consistiu então em documentar a arquitetura que havia sido construída junto com este fornecedor. Em dois meses salvamos o projeto: cliente e fornecedor entenderam o que estava sendo construído e até hoje este fornecedor atende este cliente com sucesso.

E aqui entra o “Clean Code alternativo”: em momento algum do livro é dito que arquiteturas não devam ser documentadas. Nem no livro “Clean Architecture”, publicado em 2017 algo assim é dito.

E sabe o que era mais interessante neste caso? A plataforma foi escrita em Java, mas a equipe só tinha experiência com .net. Resultado: usaram os padrões de codificação do C# para um projeto Java.

Eu e os comentários

A argumentação óbvia de que comentários em excesso são algo ruim na minha opinião é redundante: qualquer coisa em excesso é ruim. Simples assim, é uma crítica que portanto nada diz.

Mas há pontos que com o tempo foram se tornando mais claros para mim.

Código totalmente auto explicativo é uma ilusão

A história que conto de 2016 é um bom exemplo disto: para a equipe que desenvolvia a plataforma o sistema era óbvio. O problema é que existe mundo externo e a percepção deste pode ser diferente da de quem codifica. Resumindo: o que é óbvio para você não necessariamente é para o outro.

(a experiência foi meses depois do meu próprio texto que mencionei aqui – incrível como mudou de repente minha visão sobre o livro)

E não é raro encontrar pessoas que se isolam no ato de programar, geram coisas maravilhosas, que funcionam super bem mas que, infelizmente, são de difícil compreensão para o resto do time. Talvez até mesmo por terem uma formação específica que não seja a mesma que a da equipe (matemáticos, por exemplo). Nestes casos comentários agregam, e muito.

Indo além, sempre há um contexto: o código nunca existe por si mesmo. Existe um contexto em que ele foi gerado. Este contexto pode ser histórico (a situação da empresa naquele momento). Ter esta informação ajuda muito a entender por quê foi codificado daquela maneira e, mais importante: por que funciona ou não.

E há outro fator também: equipes mudam, mas raramente muda o stakeholder do projeto. E este precisa do máximo de informação possível para que possa manter sua posse sobre o mesmo.

(Knuth tentou algo similar com literate programming muitos anos antes e a ideia não vingou)

Sobre comentários “mentirosos”

Atuo profissionalmente desde 1996: na minha experiência nunca vi alguém mentir em um comentário. O que já vi foi algum comentário desatualizado. Mas sabe de uma coisa? Nestes casos quem dava a manutenção simplesmente os atualizava e o problema estava resolvido.

Nunca foi um problema.

Comentários redundantes

É chato encontrar um comentário redundante? Sim, concordo: mas nunca vi um comentário redundante ferir a produtividade de alguém. Indo além, tal como disse neste mesmo texto, normalmente quando os encontro são escritos por quem está começando e os usa para ter alguma segurança sobre o que está sendo produzido.

E aí como você resolve o problema? Simples: no momento do code review você os remove se forem realmente redundantes e explica para o autor dos mesmos por que o fez de forma civilizada.

Contextualização histórica

Em 2016 escrevi sobre como você pode usar comentários para contar a história daquele sistema. Ainda mantenho minhas posições sobre o que disse ali (só discordo da recomendação literária que faço ao final). Caso queira ler, segue o link.

Sobre a questão de créditos e autoria nos comentários

Discordo de Robert Martin quando ele diz que não faz sentido incluir créditos e autoria do código dado que temos sistemas de controle de versão.

Se você lida com código que implementa algoritmos muito específicos (matemáticos ou físicos por exemplo) é muito útil ter a autoria ali, pois fica muito mais fácil saber a quem procurar. E convenhamos: é bem mais fácil que ficar consultando log de commits, né?

Comentários como ferramenta de design

É interessante o livro não mencionar isto, mas observo em mim e outras pessoas o uso de comentários como ferramenta de design. Direto me pego escrevendo comentários antes do código que vou construir para tornar mais claro para mim o que de fato quero fazer ali.

Os escrevo no topo das classes ou funções, e na sequência simplesmente os traduzo para código fonte. E sabe o que é mais legal? Costumam virar uma documentação super útil para quem vai dar manutenção depois, pois fica claro ali qual era o objetivo inicial daquele código.

Ano passado fiquei muito surpreso ao ler isto no livro “A Philosophy of Software Design” no qual o autor descreve exatamente este processo de criação. Aliás, neste livro estão os melhores capítulos que já li sobre o tema “Comentários”. Recomendo muito a leitura, especialmente por ter um contraponto muito interessante em relação ao “Código Limpo” no que diz respeito a este assunto.

Concluindo?

Levou anos para escrever este texto, mas finalmente saiu! Na época não podia narrar estas experiências pois estava atuando no projeto que mencionei e este post poderia ter gerado um grande constrangimento desnecessário. Mas hoje com tudo resolvido, fica muito mais fácil escrever a respeito.

Me impressiona como estas vinte páginas do texto geraram problemas ao longo do tempo: nem tanto pelo texto em si, mas muito mais pelas interpretações muito equivocadas do mesmo (me pergunto inclusive se estas pessoas realmente leram este livro).

Acho que no final das contas este é o pior capítulo do “Clean Code” e aquele sobre o qual mais vejo problemas. Repito o que disse na primeira parte desta série: ainda acho importante a leitura do livro pela importância que ele tem na formação de gerações de programadores aqui no Brasil.

Espero que com esta série eu possa ter lhe mostrado como extrair um pouco mais da leitura deste livro e mesmo outros que possam seguir a mesma (pobre) linha argumentativa.

No caso deste capítulo tenho uma sensação diferente: tal como já escrevi, os textos que mais gosto são aqueles dos quais discordo pois a leitura se torna um diálogo com o qual aprendo. Não é o caso aqui: a argumentação tóxica nos trouxe problemas no futuro, e não vejo muitas pessoas escrevendo a respeito, o que só aumenta o problema.

Talvez eu escreva mais sobre o livro, mas agora vou aproveitar que voltei a escrever para falar sobre outras coisas por enquanto. Até lá!