A arte milenar de comentar códigos ABAP

Na minhas andanças por códigos alheios e códigos DMM (“de mim mesmo“) antigos, sempre acho curioso a quantidade de comentários sem sentido que encontro. Impulsionado por alguns artigos da interwebs, resolvi analisar a arte milenar de comentar códigos ABAP. Comentar… será mesmo que é sempre preciso/útil? Início este post com uma fábula sobre comentários, e depois apresento algumas novas idéias para você poder refletir sobre esta arte milenar. Coloque o seu kimono, e vamos para luta!

1 – “A treta” ou “Mauricio apanhando do próprio código”.

Quando eu comecei no mundo da programação, me disseram que “comentar códigos é uma forma de conversar com alguém que irá dar manutenção no seu programa, ou até mesmo com o seu eu do futuro“. Fiquei maravilhado com essa possibilidade de conversar através do ABAP, e, desde então, comecei a comentar freneticamente meus códigos, imaginando que aquele monte de palavras cinzas (ou azuis se você estiver no editor velho) iriam ajudar alguém algum dia.

O problema é que me falaram que eu deveria “comentar“, mas ninguém me disse quais informações eu deveria transmitir pelos comentários. Obviamente, começaram a nascer comentários infames, daquele tipo que não presta pra nada, e só enchem linguiça:

START-OF-SELECT

* Validações iniciais
PERFORM f_valida_dados_tela_seleção.

* Atualiza dados
PERFORM f_atualiza_tabela_casdatro.

* Exibe ALV na Tela
PERFORM f_exibe_alv_final.

* Análise de todas as ordens de vendas
LOOP AT t_ordens ASSIGNING <fs_ordens> .

* Verifica se o Material existe no cadastro de materiais
  READ TABLE t_material WITH KEY
    mantr = <fs_ordens>-matnr
  BINARY SEARCH.

ENDLOOP.

Esse tipo de comentário me lembra de provas dissertativas e aquele grande técnica de repetir a pergunta que o professor fez, para a resposta parecer maior.  😛

Com comentários inúteis como os acima, eu acreditava que o meu código estava muito bem comentado, e que isso ajudaria muito quem fosse dar manutenção no futuro. Ah e, obviamente, comentar o código era um pré-requisito da revisão de pares, então, quem fosse revisar meu código não poderia reclamar que ele não estava “bem” comentado.

Essa foi a técnica que eu utilizei por mais de 1 ano e meio… até que eu tive que alterar um código DMM antigo, daqueles que eu havia feito nos primeiros meses da minha carreira como ABAPer. O código era grande, continha diversos problemas estruturais e a lógica era complicada o suficiente para eu ter me esquecido o que diabos aquele pedaço de código fazia. Foi alí que eu percebi que os comentários que eu havia feito não prestavam para nada. Um pequeno exemplo para mostrar mais ou menos o tipo de comentário que eu encontrei:

* Começo da lógica sem sentido e que eu inventei agora para exemplificar o mau uso de comentários

* Análise das Ordens
LOOP AT t_ordens ASSIGNING <fs_ordens> .

* Busca o cliente
  READ TABLE t_cliente WITH KEY
   kunnr = <fs_ordens>-kunnr
  BINARY SEARCH.

  IF sy-subrc <> 0.
*   Continua para o próximo registro - não soma
    CONTINUE.
  ENDIF.

  wa_soma-vbeln = <fs_ordens>-vbeln.

* Busca o Material
  READ TABLE t_materiais WITH KEY
   matnr = <fs_ordens>-matnr.
  BINARY SEARCH.

* Efetua o cálculo
  IF sy-subrc = 0.
    wa_soma-total = v_total + <fs_ordens>-valor1 + <fs_ordens>-valor2 + <fs_ordens>-valor3.
  ELSE.
    wa_soma-total = v_total - ( <fs_ordens>-valor5 + <fs_ordens>-valor6 ).
  ENDIF.

* Sumariza os valores
  COLLECT wa_soma INTO t_soma.

  ...

ENDLOOP.

Esse código aí em cima está comentado, mas nem de longe está bem comentado. Para que serve essa soma? E porque aquelas validações existem? Como assim uma ordem tem um cliente que não existe na “tabela de clientes”? Porque, um material é inválido para a soma?

Pessoas mais experientes conseguirão pseudo-facilmente achar as respostas para essas perguntas, se fizessem uma análise depurando o código, ou até mesmo lendo a Especificação Técnica / Funcional. Mas eu era um ABAP Júnior, no meio de um código de 5 mil linhas… e vou te falar: sofri MUITO para entender porque a soma estava errada ali no código.

Será que dava para eu ter sofrido menos, só mudando um pouco os comentários?

2 – Como o meu eu do passado poderia ter ajudado meu eu do futuro

Todo mundo já fez comentários idiotas no código algum dia. Isso é normal. O que não deve ser normal, é você cair na síndrome do robô e continuar fazendo comentários idiotas para sempre. Muitas vezes somos orientados desde o início à errar, pois aprendemos algumas coisas de maneira errada. Mas a situação ali de cima me fez pensar um pouco em como comentar melhor meu código.

Separei algumas reflexões sobre o uso de comentários que poderiam ter me ajudado, a partir de artigos que li em diversos lugares da web. Para o compilado deste post, usei de base artigos bem bacanas do CodingHorror sobre comentários, e também a página de comentários do tutorial de C++ do Learncpp.com. Na época li outros sites, mas a mensagem é, basicamente, a mesma.

E vamos começar nossa jornada de reflexões jogando no lixo todas as redudâncias:

“Se o seu comentário explica exatamente a mesma coisa que alguém entende ao ler o comando, ele não serve para NADA”  

Bom, só isso já mata praticamente todos os comentários do código da parte 1 deste post. Pra que explicar num comentário que eu vou entrar no bloco que faz validações, se o nome do FORM já me indica isso? Isso nos leva à próxima reflexão:

“Comentários não devem explicar O QUE o código está fazendo, eles devem mostrar PORQUE aquela lógica precisa existir”.

Este conceito é uma extensão do primeiro. Se levarmos em conta aquele trecho de código ali em cima, podemos dizer que aquele comentário “Efetua o cálculo” é um comentário bem inútil. Aliás, em momento algum os comentários me explicam o porque eu tive que faze aquelas várias operações: somar os valores de forma diferente de acordo com a busca do material, ou ignorar a soma da linha caso o cliente não exista..  Eles só me dizem o óbvio, tornando-se comentários descartáveis.

Mas então quer dizer que eu posso dar CTRL+C, CTLR+V da EF no código? Diz a lenda que…

“…os melhores tipos de comentários são aqueles dos quais você não precisa.”

Um bom indicador para analisar se o seu código está “limpo” e têm fácil manutenção, é verificar quantos comentários estão espalhados pelo fonte. Normalmente quando você teve que usar muitos comentários para conseguir explicar o que o seu código está fazendo, pode ser a hora certa para re-escrever aquela lógica.

A arte de comentar está diretamente ligada à outra arte muito ignorada por programadores: A arte milenar de nomear variáveis e blocos do programa. Com nomes melhores de variáveis e de FORMs/Métodos/Funções, o seu código fica muito mais claro e direto, com relação às suas maléficas intenções.

Para vocês terem idéia do quanto essa questão de “saber dar nomes aos bois” é importante, tem até livros falando sobre como manter o seu código bem escrito, como este aqui. Neste livro, o autor defende a tese de que comentários são necessários somente quado há uma falha do programador em se expressar através do código fonte. É uma idéia bem extrema, mas muitos programadores concordam com ele.

No nosso caso, quase sempre trabalhamos com desenvolvimentos cheios de regras de negócios complicadas, e com tabelas/campos/funções/classes/métodos com nomes em alemão. Logo, nós precisamos sim de comentários nos códigos ABAP. Um dica legal para você começar a escrever códigos mais auto-explicativos é a seguinte:

“Programe como se o recurso de comentar códigos simplesmente não existisse”

Imagine um mundo onde o compilador não reconhecesse o ‘*’ nem o ‘”‘ como caracteres de início de comentários. Um mundo onde você ainda tem que se comunicar com outros programadores e até com o “você-mesmo-do-futuro” através do código. Neste mundo, a tarefa de criar um código fica muito mais interessante! A não ser que você seja um troglodita, obrigatoriamente, você tem que se preocupar fortemente com a estrutura do seu código, com os nomes de variáveis e de todos os outros objetos.

Entrar neste mundo da próxima vez que você começar a programar, deve ajudar o seu código a ficar muito mais auto-explicativo. A tarefa vai ficar bem mais difícil, mas a regra aqui é a boa e velha “no pain, no gain”!

 3. Para ler mais

Existem quilos, litros e toneladas de artigos sobre comentários na internet.  Uma pequena busca pelo assunto no StackOverflow e você vai acessar muitas boas discussões sobre o assunto.

Neste post utilizei como base esta página de um tutorial que segui recentemente, quando estava estudando C++.  Foi ela que me lembrou que eu ainda tinha que falar deste assunto aqui no site. Recomendo também este e este outro artigo do Coding Horror. Em ambos os sites, leia também os comentários, para entender como as pessoas reagem à reflexões desse tipo.

4.  E viva o debate!

Eu, particularmente, tento entrar naquele mundinho onde comentários não existem, mas recorro aos comentários para explicar partes complicadas da regra de negócio, ou para explicar alguma lógica mirabolante que eu precisei fazer. O ideal pra mim é que a pessoa consiga dar manutenção no código sem precisar olhar um documento externo.

Outro coisa que eu gosto muito de fazer, é explicar de forma geral o que determinado bloco de código faz, como se eu estivesse preparando o leitor antes de chegar na lógica pesada. Isso, aliás, já me ajudou quando eu estava dando manutenção em programas antigos que eu mesmo tinha programado.

Mas e você, segue alguma dessas coisas? Ou acha que é tudo baboseira, e comenta freneticamente coisas sem sentido? Ou talvez você escreva letras de música nos comentários, para deixar o código mais “cool”?  Deixe a sua opinião e vamos todos discutir juntos!

** Finaliza o post de hoje mandando um abraço. Sim, eu sou um comentário inútil.
Abraços e até a próxima!