Não comente seu código

Você usa desodorante nas axilas? Se usa, provavelmente o faz por causa do mau cheiro produzido
pelas suas glândulas sudoríparas dessa região.
É por um motivo semelhante que muitos programadores escrevem comentários. Seu código é difícil
de compreender, por isso precisa ser comentado. Mas se o código ruim fosse refatorado até se
tornar um bom código, a maioria dos comentários seriam desnecessários.

1 - Comentários como desodorante
Com a ajuda do Martin Fowler no seu livro sobre refatoração, me dei conta de que muitos dos
comentários que eu escrevia no passado eram usados para minimizar os efeitos de um código ruim
(do ponto de vista da clareza, não da eficiência). O código ruim, segundo Fowler, cheira mal e os
comentários, neste caso, agem como desodorante. A seguir, alguns desses maus usos de
comentários.
1.1 - Para compensar a má nomeação de identificadores
Se você sentir a necessidade de comentar pra que serve uma váriável, constante, função,
parâmetro de função, atributo, classe ou método*, provavelmente o nome que você deu ao
identificador não é um bom nome.
Sem ser dogmático, sugiro o seguinte:
'Quando você sentir a necessidade de escrever um comentário para explicar o que faz ou pra que
serve determinado identificador, transforme o comentário que você escreveria no nome do
identificador.' (uma adaptação de algumas frases do Fowler)
Transformar um comentário curto em um nome de variável é fácil (a menos que você use uma
variável para várias coisas diferentes). Mas, transformar um comentário de várias linhas em um
nome de função dará mais trabalho, porém, neste caso, os comentários longos são consequência
de um outro problema: funções longas.
1.2 - Para compensar a escrita de funções longas
Quem escreve uma função com muitas linhas, normalmente sente a necessidade de adicionar um
comentário junto à declaração da função para explicar as coisas que ela faz. No corpo de funções
desse tipo, também é comum encontrar comentários para explicar certos agrupamentos de código.
Em ambos os casos, os comentários são um indício de que o código não está suficientemente claro.
Ao invés de se eximir da responsabilidade pelo mau código atrás de comentários, refatore o código
desmembrando a função longa em várias funções menores. Se há comentários ao longo do corpo
da função, esses comentários dão uma dica do que pode ser extraído e do nome que você pode dar
a cada função extraída.
Laços com muitas linhas de código dentro de uma função são terríveis para compreender,
especialmente laços aninhados. Se você reduzir o número de linhas dentro de um laço de forma que
possa observar sem usar scroll onde começa e onde termina o laço, seu código será mais fácil de
compreender.

} Apesar de o código acima permitir uma fácil compreensão. evita erros.tende a ser mais adequado. em inglês). o compilador perceberá. respectivamente. String getInscricaoFormatada2(int tipoInscricao. Nestes casos.Para organizar o pensamento sobre o código Quando não uso um quadro ou papel para rascunhar o que vou codificar. 3. } A alternativa "B" é preferível porque. À medida que os passos são concluídos.999/9999-99". inscricao).999. é útil marcar o código duvidoso com um comentário precedido por um "TODO" ("fazer". 3 . Aqui vão alguns dos usos que considero adequados.999-99".Quando usar comentários? Tudo bem se você achar que estou sendo contraditório neste tópico por causa do título que escolhi para o artigo. Se o programador decidir usar os literais 1 e 2 em todo código que lide com os tipos de inscrição. além de dispensar o uso de comentários. Exemplo (em Java): /* Exemplo A */ String getInscricaoFormatada1(int tipoInscricao. inscricao). removo os comentários. else if (tipoInscricao==2) /* 2=CNPJ */ return formatarTexto("99. enquanto ele não poderá ajudar se você fizer uso de um literal incorreto. em certo programa.que não usa comentários .Para marcar código duvidoso. passível de melhora ou incompleto Há casos em que algumas suposições precisam ser temporariamente assumidas como verdadeiras para que a codificação flua sem empecilhos. uso comentários para criar uma lista de passos que preciso seguir para atingir o objetivo do código. Alguns exemplos: /* TODO: confirmar se o DV da conta é calculado com módulo 10 */ /* TODO: refatorar este código para remover as duplicações /* .1. inscricao). 3. Se você digitar incorretamente o nome de uma constante ao fazer uso dela. else return inscricao. pois nesse ponto se tornam irrelevantes. ele provavelmente compensará isso com o uso de comentários. else if (tipoInscricao == TIPO_INSCRICAO_CNPJ) return formatarTexto("99.Para explicar o uso de strings e números literais Strings e números literais são valores escritos diretamente no código.3 .1 .999/9999-99". inscricao).999. A verdade é que eu gosto dos comentários. String inscricao) { if (tipoInscricao==1) /* 1=CPF */ return formatarTexto("999. o próximo código .2 . O mesmo se dá com códigos passíveis de melhora ou incompletos. apenas precisam ser "persistidos" em algum lugar para que eu não esqueça deles. /* Exemplo B */ static final int TIPO_INSCRICAO_CPF = 1.999.999. Por exemplo. Esses passos não precisam ser precisos. pode ser convencionado que os tipos de inscrição CPF e CNPJ serão representados pelos inteiros 1 e 2. static final int TIPO_INSCRICAO_CNPJ = 2. else return inscricao.999-99". desde que não sejam usados como desodorante. String inscricao) { if (tipoInscricao == TIPO_INSCRICAO_CPF) return formatarTexto("999.

para fins de simplificação. */ Conclusão Para encerrar. partly * because it maintains all the allocation infrastructure (which isn't * needed. 3. Quando não é óbvio o porquê de uma decisão e você não esclarece isso com comentários. duas ótimas citações: "Qualquer tolo consegue escrever código que um computador entenda.Para explicar porque você fez algo Há certas ocasiões em que você precisa explicar porque fez algo no código .specialized allocator for internal objects * * Copyright (C) 2006 Linus Torvalds * * The standard malloc/free wastes too much space for objects. but even * more because it ends up with maximal alignment because it doesn't * know what the object alignment for the new allocation is. torne o código mais simples . Crédito da foto: George Marks Referências:  Martin Fowler." (Martin Fowler) "Sempre codifique como se o programador que vai dar manutenção no seu código fosse um serial killer maníaco que sabe onde você mora. ao assumir o seu trabalho.o que pode levar a falhas que ele não tem condições de prever ou a um mau desempenho. "Refatoração: aperfeiçoando o projeto de código existente"  Jeff Vogel.c . há o risco de que algum programador. "Six ways to write more comprehensible code" . quando eu disser "variável".especialmente quando isso torna o código mais complexo. Um bom exemplo é um comentário escrito por nada menos que Linus Torvaldsnum arquivo fonte do Git (em C) para justificar a criação de um alocador de memória especializado ao invés de utilizar a função malloc() padrão: /* * alloc. Bons programadores escrevem código que humanos possam entender. variável e atributo são coisas diferentes." (autor desconhecido) Gostou do que leu? Deixe seu /*comentário*/. — * ^ A rigor. estarei me referindo também a "atributo" e quando disser "função" estarei me referindo também a método.3 ./* TODO: validar campos obrigatórios antes de gravar /* PS: IDE's de desenvolvimento modernas permitem a fácil localização dos comentários marcados com "TODO". since we never free an object descriptor anyway). Mas. assim como função e método.

The Clean CoderRobert C. // tempo transcorrido em dias int tempoTranscorridoEmDias. int[] diaMarcado = new int[3]. int diasReaisDeTrabalho = 4. i++) for (int dia = 0.Frederico Maia Arantes• 5 anos de experiência em Desenvolvimento de Software. dia < mes. int diasDesdeModificacaoDoArquivo. 5. Programador desde 1970. Funcionar é o mínimo que se espera 12. } } 22. Martin (Uncle Bob).. E ao meu lado hoje. } } return diasMarcados.rodrigokono.NET• Palestrou em mais de 12 capitais• Mais de 14. for (int i = 0. private string pszqint = "102".Não tenho tempo parafrescura!Meu chefe está mepressionando!Quero mostrarprodutividade. } class Cliente { private DateTime gerarDataHora. Nomes significativos int d. Use nomespronunciáveis 24.Clean Code: A Handbook of Agile Software Craftsmanship.. dia++) { { if (x[0] == 4) if (diaMarcado[STATUS] == MARCADO) { { lista1. j < NUMERO_DE_TAREFAS.Agile Software Development: Principles.Técnicas para um código limpo                           1.marcado) { diasMarcados. int idadeDoArquivoEmDias. } } } } return lista1. Nomes significativos public List<int> obtemDiasMarcados() { int[] diaMarcado = new int[3]. Ah! Mas o cronograma éapertado. 1995. Filho feio não tem pai! 14.net 2. Patterns and Practices. MCP@rodrigokonowww. Como mensurar aqualidade de um código? 17. MCT. j++) { s = (t[j]*4)/5. } 25. foreach (Dia dia in mes) { if (dia. Nomes significativos class DtaRcrd102 { private DateTime gerdmahms.NET• Dez anos de comunidade . • Eficiente• Simples• Direto ao ponto• Mínimas dependências• Sem duplicação• Fácil manutenção• Padrões definidos• Fácil leitura e entendimento• Coberto de testes• Elegante Síndrome da janela quebrada 9. int diasDesdeCriacaoDoArquivo. 13. private string idRegistro = "102". Você é um programador2. } 23. MCTS. Afinal. "Qualquer um consegue escrever código que um computador entende. int soma = 0. 7. Há duas razões pelas quaisvocê está nesta palestra:1. private DateTime moddmahms. private DateTime modificarDataHora. j++) { int tarefasPorDia = trabalhoEstimado[j] * . Que porta representa o seu código? 10. Rodrigo Kono• MVP Microsoft• MCP – MCTS – MCPD – MCT• Foco em desenvolvimento WEB• Developer na LG Sistemas• Fundador do DevGoiás.Add(diaMarcado[STATUS]). MCPD. Boas PráticasClean CodeTécnica para um código limpoRodrigo KonoMVP. i < lista.• Membro e coordenador do Grupo de Usuários Java de Goiás (Gojava).Livros:Designing Object-Oriented C++ Applications using the Booch Method. ÓTIMO! PRECISAMOS DE PROGRAMADORES MELHORES C. de quem é a culpa? 15. É nossa! 16.Add(dia). } const int DIAS_DE_TRABALHO_POR_SEMANA = 5. OK! Vamos ao que interessa 18. Bons programadores escrevem código que humanos endentem“ Martin Fowler 11. Martin Robert 6. 4. Nomes significativos for (int j = 0.• 2 anos de experiência como instrutor de treinamentos. 20. 2002.. j < 30. Use nomes buscáveis 26. List<int> lista1 = new List<int>(). NOMESSIGNIFICATIVOS 19. return diasMarcados.• 3 anos de experiência em Desenvolvimento Java.500 pessoas nesse tempo• Finalista Imagine Cup 2005 – Brasil/Japão 3.Fundador e Presidente Object Mentor Inc. Deseja se tornar um ainda melhor.Add(x[0]). diasMarcados. List<int> diasMarcados = new List<int>(). Use nomes que revelem a intenção 21. for (int j = 0. List<Dia> diasMarcados = new List<Dia>(). O que é Clean Code? 8. Nomes significativos public List<int> obter() public List<int> obtemDiasMarcados() { { int[] x = new int[3].

Seja pequeno 31. Comentários• Comentários sobre licença (direitos de uso de uma lib. FORMATAÇÃO 49. Comentários não ajudam um código sujo! 42. Objetos e estrutura de dados 54. Funções• Seu código deve ser lido como uma narrativa• Temos sujeitos. Funções• Menos é mais!• Extraia trechos em métodos privados. } 27. Objetos e estrutura de dados 53. 32. etc. FUNÇÕES 30. DRY (Don’t Repeat Yourself) 40. soma += taredasPorSemana.• Extraia para um método que faça o que diz! 43. O que vale é a regra do time 50. Funções• Repare a endentação (sim.• Um bom código é autodocumentado. Abstração de dados 52. Tratamento de exceção é uma dascoisas que um método ou função faz 61. Comentários 48. não são bons. A lei de Demeter 55. é assim que escreve)• Muitos níveis ~= muita responsabilidade• O método deve fazer uma única coisa. 38. Não use exceções genéricas 62. 37. Funções 33. Funções• Muitos argumentos = code smell• Existem algumas regras para a quantidade de argumentos• Argumentos booleanos. Comentários• Por falta do que escrever• Redundantes• Documentação em APIs não públicas• Dizendo algo que o próprio código deveria dizer• Código comentado =S 47. Exceções ao invés de código de erro. Perfil. Tratamento de erro• Obriga o uso de if• Pode dispara NullPointerException• Considere: Lançar exceção ou retornar um objeto especial 64. Estoque. Não retorne null 63. OBJETOS E ESTRUTURA DE DADOS 51. 35. Não passe null . COMENTÁRIOS 41. Funções 39. verbos e predicados• Narrativas são frases em ordem coerente• Lembre-se disto ao extrair em métodos privados. 58. Faça uma coisa só! 34. Comentários aceitáveis 44. em geral. Nomes significativosClasses representadas por substantivos ex: Cliente. int taredasPorSemana = (dias / DIAS_DE_TRABALHO_POR_SEMANA). Tratamento de erro 60. etcMétodos representadas por verbos ou frasesverbais ex: enviarPagamento. TRATAMENTO DE ERRO 57. Nomeando classes e métodos 28. por exemplo)• Comentários informativos• Necessidade de explicação de negócio 45. Comentários• Em geral. e bem!• Está fazendo mais de uma coisa? Extraia.                                      diasReaisDetrabalho.• Lembre-se dos nomes significativos• Vá direto ao ponto. servem para explicar um código ruim. Objetos e estrutura de dadosUm método F de uma classe C só conhece:• Métodos de C• Objetos criados por F• Objetos passados como argumentos para F• Objetos em variáveis de instâncias de C 56. 29. salvar. Leia o código de cima pra baixo 36. Tratamento de erro 59. Comentários ruins 46.

66. Não deixe acumular problemas! 67...Torna o seutrabalho lento edesgastante com opassar do tempoPode arruinar seuprojeto. falar é o primeiro passo de melhoria. Portanto. Código ruimcheira mal.     65..Fique atento.net/hebelThiago Faria de Andradehttp://www.slideshare. carreira.empresa.net/gustavocsbHendrik Ebelhttp://www.slideshare. Falar é fácil! O desafio é criar um código de qualidade.Gustavo Barbosahttp://www.net/thiagofa .. 68. Using References.slideshare. REGRA DOS ESCOTEIROSDeixe a área do acampamentomais limpa do que como você aEncontrou. 69.

Hoje vejo isso como um absurdo (para não dizer outra coisa). particularmente sou defensor de um código não comentado. Em conversas com outros desenvolvedores alguns reclamavam porque que se viam obrigados a comentarem seus códigos para poderem passar pelas auditorias internas. como assim. Seu código deve ser expressivo Para tentar demonstrar um código expressivo imaginei um exemplo onde seja necessário implementar um método que aplique descontos nas mensalidades dos alunos do 5° período ou superior. todas as suas linhas não conseguem refletir o seu verdadeiro objetivo. agora some a isso o esforço de atualização também do comentário. Código com necessidade de comentário Abaixo apresento o método “AplicarDescontosMensalidades” refatorado. código não comentado? Esse cara está ficando louco? Mas não falem mal de mim ainda vou explicar o meu ponto de vista. nessa situação os comentários “podem” auxiliar o uso da biblioteca. . o uso de bibliotecas de terceiros que às vezes não apresentam o funcionamento esperado e. com um código mais expressivo. Se você sentiu a necessidade de comentar seu código é porque até você está percebendo que o mesmo não está expressivo e. Muitos devem estar se perguntando agora. Um código muito comentado pode trazer outro problema: a manutenção do próprio comentário. ou com o mínimo de comentários possível.A falsa impressão de um bom código Desde de quando comecei a trabalhar com desenvolvimento de software. Um código comentado quase sempre é sinal de código ruim. mesmo sendo refatorados. Muitos comentários podem mesmo ser parâmetro para definir um bom código? Eu. Um outro caso que também pode caber comentários é quando estamos desenvolvendo uma biblioteca para ser utilizada externamente. Podemos citar por exemplo. e que tenham o coeficiente de rendimento maior ou igual a 7. para facilitar a vida dos outros desenvolvedores que futuramente irão dar manutenção no código. ouvia sempre uma frase que é muito repetida até hoje que diz que: “Código bom é código comentado”. nesses casos somos obrigados a comentar determinados trechos. Sabemos da dificuldade que é em muitos casos dar manutenção em um código de produção. Mas ainda permaneço com o pensamento que podemos sempre buscar alternativas para evitar os comentários. Acredito que tem certos códigos que realmente são difíceis de serem expressivos.

percebe-se que o mesmo está mais expressivo e o seu objetivo se mostra mais claro para quem lê o código do método agora. que diz a sua intenção tanto nos nomes dos métodos que o compõe. mais importante que ter um código muito comentado é ter um código expressivo. Martin (Uncle Bob) cita no seu livro Código Limpo “Habilidades Práticas do Agile Software”. mas sim levantar a questão que. Ao sentir a necessidade de fazer um comentário. Meu objetivo aqui não é condenar totalmente os comentários no código fonte. uma frase que diz muito sobre o pensamento que tenho: “O único comentário verdadeiramente bom é aquele em que você encontrou uma forma para não escrevê-lo”. espero que tenha conseguido passar o recado e que agora vocês analisem bem a real necessidade dos comentários nos seus códigos. Robert C. É isso ai. pare e reflita sobre a sua real necessidade. . quanto nas suas linhas. esse sim é um tipo de comentário que aceito e recebo com prazer . Para qualquer feedback deixe seu comentário.Código refatorado sem a necessidade de comentário Depois de refatorar o código do método “AplicarDescontoMensalidades”. faça sempre as perguntas: Porque tem que ter esse comentário? O código fica claro sem o comentário? Outros desenvolvedores irão entender mesmo esse código? E se possível procure sempre mostrar seu código para outros desenvolvedores da equipe e receber feedbacks sobre o mesmo.

elaborado ou grande. evite usar ele desnecessariamente. Use comentários para explicar o que é o programa. . para que serve. comentando printf e outras coisas óbvias: 'agora exibimos a mensagem'.Use comentários com moderação Use comentários com moderação Embora seus comentários não prejudiquem o funcionamento de seu programa em C. qual a utilidade de um algoritmo que é mais complexo. 'agora somamos os números' etc.

Martin. Código Limpo .  Será que comento esse bloco de código?  Minha função está objetiva?  Será que esse nome de variável ficou bom?  TDD atrapalha na expansão de um projeto? O autor tenta deixar bem claro que o objetivo não é vender seu padrão de desenvolvimento como uma verdade absoluta. mas visando melhorar meu entendimento sobre o que é um bom código comprei o livro Código Limpo. na verdade esse pensamento deveria existir toda vez em que escrevemos qualquer trecho de código. neste livro são apresentadas práticas boas e ruins de desenvolvimento. do autor Robert C. um ótimo lugar para aprender algumas práticas que sempre criaram dúvidas. além de mostrar o que não gosta e consultar programadores responsáveis por projetos e linguagens conhecidas para reforçar seu ponto de vista. confira alguns exemplos de perguntas que serão respondidas após a leitura.Código Limpo Todo programador em algum momento já se perguntou se realmente está gerando bons códigos. ao invés disso Robert tenta mostrar como trabalha e o que acha uma boa prática.

Tratamento de Erro 11.O grande ponto de reflexão é não se contentar em fazer um código funcionar. Introdução 3. Concorrência 17. Sistemas 15. Características Internas do JUnit 19. Sobre a Capa 4. pois segundo o autor. Odores e Heurísticas . mas utilizar padrões e facilitar o entendimento de um código é o que realmente faz de você um bom programador. Formatação 9. Refatorando o SerialDate 20. Código Limpo 5. Sumário Resumido 1. Comentários 8. Limites 12. Prefácio 2. Refinamento Sucessivo 18. fazer um código funcionar é muito fácil. Testes de Unidades 13. Nomes Significativos 6. Classes 14. Objetos e Estruturas de Dados 10. Emergência 16. Funções 7.

sendo que nenhum parâmetro é o ideal. ao invés de escrever um comentário. deixando bem claro que quanto menos parâmetros melhor. além disso cada função deve fazer apenas uma coisa. ainda mais em variáveis. em muitos casos comentários são adicionados para aliviar a consciência do programador após ter feito um código ruim. mas fechadas para alterações. Basicamente se sua função está grande ou faz mais de uma coisa. ou seja. extraia funcionalidades diferentes de dentro da sua função e crie uma nova. . nomes significativos para o contexto do código. cada classe só pode ser responsável por uma coisa. sempre passando dicas e fazendo comparações de códigos com nomes significativos e códigos com nomes confusos. se for private coloque em baixo da função que utilizar. desde variáveis até classes. reescreva seu código. Comentários Os pontos citados pelo autor sobre comentários em código são ótimos. Um ponto interessante nesse capítulo é quando o autor fala sobre os parâmetros das funções. por exemplo. é o que todas as funções devem ser. se você precisar descrever uma classe e utilizar as palavras “se”. onde as classes são abertas para expansão. refatore seu código. “ou” ou “mas”. sendo assim. principalmente em códigos que não serão disponibilizados como API pública. logo não é necessário utilizar documentação. ou seja.Nomes Significativos Nesse capítulo o autor apresenta motivos para se escolher bons nomes. devemos seguir o princípio da responsabilidade única. além disso também é recomendado organizar o código de tal forma que faça valer o princípio de aberto-fechado. Ex: Javadoc. tenho más notícias para você. mesmo que isso seja difícil de ocorrer. Classes Este capítulo tem alguns detalhes parecidos com os que foram vistos para funções. Também posso destacar a passagem de comentários redundantes. “e”. refatore seu código. Confira algumas dessas dicas:  Evitar informações erradas  Faça distinções significativas  Use nomes pronunciáveis  Não utilize abreviações Funções Pequenas. coisa que o autor considera horrível.

torne este mais legível. não tente programar para provar que você conhece recursos que ninguém mais conhece. em diversos pontos do livro é esclarecido que a verdadeira documentação de um projeto é o seu código. . comentários e etc.Tradução do Livro Apesar de apresentar um excelente conteúdo. O legado de seu projeto é o seu código. sendo assim. tudo isso está sujeito a erros. principalmente em códigos que são alterados com frequência. infelizmente é algo quase que comum em livros técnicos estrangeiros. em certos pontos fiquei chateado pelos erros de tradução. mas irá ajudar muito na maneira de pensar antes de programar em qualquer linguagem. Conclusão Este livro não visa melhorar seus conhecimentos em uma determinada linguagem. programe para o projeto e para sua equipe. documentação técnica.