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 …

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 )
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:

// 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
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:

/**
 * 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 .

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

Tags: comentarios, ddd, fluent interface, Java, lprodjava, produtividade

Filed in Java

Reader's Comments

Wallace Silva | 16 Sep 2009 11:53 am
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
Tiago dos Santos | 16 Sep 2009 3:05 pm
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
- Urubatan | 16 Sep 2009 3:22 pm
  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
  Reply to this comment
  - Tiago dos Santos | 16 Sep 2009 4:00 pm
    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
Guilherme Chapiewski | 17 Sep 2009 11:38 am
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
Andre Brito | 18 Sep 2009 1:50 pm
Já conhecia tudo isso, mas é sempre bom relemebrar
Tá de parabéns.
Reply to this comment
Rodrigo Machado | 18 Sep 2009 7:03 pm
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
dejaime | 29 Oct 2009 12:53 pm
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
Seja comunicativo, diga por que escreveu este código » Blog do Urubatan | 07 Jan 2010 12:28 pm
[...] 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