Blog do Urubatan
msgbartop
Desenvolvedor, Palestrante, Escritor, Nerd Assumido e Pai do Marcus :D
msgbarbottom

16 Sep 09 Não seja repetitivo, nunca comente o que o seu código faz

Eu sei que já falei sobre comentários antes, mas acho que a abordagem não agradou muito, a maior parte das pessoas leu só o título do post e não prestou atenção no texto, então vamos tentar uma abordagem diferente.
Este post é o primeiro de uma série de 2, o próximo post vai dizer que é necessário comentar o código, mas com comentários decentes, então, sem gritaria por aqui por enquanto, ok?
Mas vamos ao que interessa …
Na minha opinião, qualquer programador Java, ou até mesmo, qualquer programador, que colocar os olhos no código abaixo, vai entender quase que instantaneamente o que ele faz, se alguem não concordar com isto, avise por favor …

1
2
3
4
5
6
new EmailMessage()
    .from("exemplo@urubatan.com.br")
    .to("gerente@empresa.com")
    .withSubject("Aprovação de processo")
    .withBody("Descrição bastante detalhada do que precisa ser aprovado")
    .send();

(sim, copiei o exemplo do blog do GC :D )
Então, eu acredito que se alguem quiser colocar um comentário neste código dizendo algo do tipo:

  • Envia email
  • Cria uma mensagem de email, configura propriedades e depois envia

Vai estar simplesmente sendo repetitivo, e poluindo o código com comentários inúteis, isto seria dizer o que o código faz, e se você comenta o que o seu código faz você é sim um perdedor que gosta de jogar trabalho no lixo!
Ahh, mas e se meu código não é assim tão claro? E se meu código é parecido com isto:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// create some properties and get the default Session
Properties props = new Properties();
props.put("mail.smtp.host", _smtpHost);
Session session = Session.getDefaultInstance(props, null);
 
// create a message
Address replyToList[] = { new InternetAddress(replyTo) };
Message newMessage = new MimeMessage(session);
if (_fromName != null)
    newMessage.setFrom(new InternetAddress(from,
        _fromName + " on behalf of " + replyTo));
else
    newMessage.setFrom(new InternetAddress(from));
    newMessage.setReplyTo(replyToList);
    newMessage.setRecipients(Message.RecipientType.BCC, _toList);
    newMessage.setSubject(subject);
    newMessage.setSentDate(sentDate);
 
// send newMessage
Transport transport = session.getTransport(SMTP_MAIL);
transport.connect(_smtpHost, _user, _password);
transport.sendMessage(newMessage, _toList);

Bom, se o seu código é assim, então você precisa estudar um pouco de refactoring :D
Ahh, mas estou alterando uma parte da aplicação com muito código legado …
Bom, você deveria utilizar pelo menos alguns “extract method” para facilitar um pouco a leitura, e não comentar o que o código faz.

Imaginem a seguinte cena:
Você esta caminhando na rua e entra em uma loja, no momento em que você entra na loja, vê uma placa escrito: Roupas masculinas
Dois passos adiante, um vendedor chega e diz: Senhor, aqui o senhor vai encontrar roupas masculinas
Mais alguns passos e outro vendedor: Vendemos roupas masculinas aqui senhor.
E mais outra placa dizendo: Aqui roupas masculinas

Se você ainda estiver na loja e não bater no próximo que lhe visar que ali são vendidas roupas masculinas, no mínimo acabou de ocorrer um desperdício absurdo de esforço para informar exatamente a mesma coisa.
E este caso do email não é um dos mais comuns, o motivo deste post é que em muitos lugares eu vejo código parecido com:

1
2
3
4
5
6
/**
 * Set's the active property
 */
public void setActive(boolean active) {
   this.active = active;
}

(Isto não é uma critica a ninguém especifico e a todos os que já escreveram código assim, não foi uma nem duas vezes que vi isto por ai …)
um método de nome “setActive” com o comentário “Set’s the active property” é no mínimo redundância, e desperdício de tempo.
Então, eu não estou dizendo, nunca comentem o seu código, mas estou dizendo, se você precisa dizer o que o seu código faz, o seu código tem problemas, mas comentários são úteis, principalmente em interfaces públicas se você estiver informando por que ou como o código faz o que faz …
Mas tenha como regra, é proibido um comentário dizendo o que o código faz, pois ele é um sinal de que o código esta muito ruim!!

Ahh, e só para terminar, a biblioteca que permite aquele código de envio de emails bonitinho é a “Fluent Mail API” e o nome desta “técnica” é “Fluent Interfaces”, uma “técnica” bastante utilizada por quem trabalha com “Domain Driven Design”, e DDD faz Orientação a Objetos realmente mais divertida e mais útil, vou falar mais sobre isto em breve :D .

If you enjoyed this post, make sure you subscribe to my RSS feed!

Tags: , , , , ,

Reader's Comments

  1. |

    Urubatan, no mundo sap a regra dos comentários é invertida, comente seu código ou então morra. As vezes pareço um idiota escrevendo em portugues o que o código faz. Um dia esse paradigma será quebrado, eu espero ! Um bom comentário de um livro de turbo C dos anos 90 “Bons comentários não melhoram uma má codificação, mas maus comentários podem comprometer seriamente uma boa condificação”

    Reply to this comment
  2. |

    Realmente, se for um código bem escrito, limpo, não há necessidade de comentários… Porém o que mais vemos por ai são códigos mau-escritos, sujos, complexos… nesses eu até gostaria que houvesem comentários, mas simplesmente não existem, o que dificulta muito a leitura.

    Reply to this comment
    • |

      Mas se o código for mau escrito, o ideal é refatorar o mesmo, por que o comentário não vai te ajudar muito quando precisar saber por que a porquera não funciona :D

      Reply to this comment
      • |

        Certo, concordo, mas aqui não tenho liberdade para refatorar o código pois é uma outra empresa que desenvolve (estou aqui só pra manutenção e pequenas melhorias) e é alegado que vai perder a compatibilidade do código (…), então alguns comentários dizendo oq eles queriam que o código fizesse iria me poupar algum tempo.

        Reply to this comment
  3. |

    Vc quase escreveu o mesmo post que eu escrevi em abril: http://guilherme.pro/2009/04/05/why-i-dont-write-code-comments/

    :) :) :)

    [ ]s, gc

    Reply to this comment
  4. |

    Já conhecia tudo isso, mas é sempre bom relemebrar :)
    Tá de parabéns.

    Reply to this comment
  5. |

    Muito bom esse post. Há muito tempo penso dessa maneira e sempre procurei as palavras para expressar minha opinião quanto a (falta de) necessidade de documentação e quanto a documentação excessiva prejudica a legibilidade de código.
    Sou adepto de Domain Driven Design e acredito que se você expressar os conceitos de negócio na forma de código, não somente seu código será mais legível como também será mais fácil dar manutenção, mais fácil será a transferência de tecnologia e mais fácil será a leitura.
    Talvez seja um pouco forte demais falar “perdedor”, a final, muitas pessoas estão aprendendo, mas um engenheiro de software sênior ou pleno no paradigma O.O. vai concordar com este post na íntegra.

    Abraços!

    Reply to this comment
  6. |

    Trabalho com programação há vinte anos. Sou contra tautologia, mas alguns comentários que escrevi e – na época – me pareceram ridículos, depois me foram de grande valia. O que parece óbvio na hora da codificação, nem sempre continuará sendo no futuro.

    Por isso, recomendo a todos que estão iniciando com programação: abusem de comentários, o tempo que você “perde” agora será valioso daqui a alguns meses ou anos …

    Quando o assunto é “comentário” é melhor pecar por excesso que por falta. É igual a caldo de galinha… não faz mal a ninguém.
    Concordo que a qualidade do código será a mesma, independentemente da quantidade/qualidade dos comentários.

    Dejaime

    Reply to this comment
  7. |

    [...] no último post eu disse para você não ser repetitivo, e não escrever nos comentários o que o seu código faz. Se você precisa comentar o que o seu [...]

    Reply to this comment

Leave a Comment