13 Nov 08 Comentário no código é para os fracos
Provavelmente serei crucificado por causa deste post, mas se você se der ao trabalho de ler até o final, provavelmente vai concordar comigo que comentários no código são para os fracos, programador hardcore de verdade escreve código legível!
É exatamente isto que eu estou dizendo, por exemplo, o que faz o código abaixo?
1 2 3 4 5 6 7 8 9 10 | public String write(StringBuilder fle, StringBuffer con) { File f = new File(fle.toString()); FileReader fr = new FileReader(f); BufferedReader br = new BufferedReader(fr); String lin; while((lin=br.readLine())!=null){ con.append(lin).append("\n"); } return con.toString(); } |
Difícil? E este ainda é um código simples, mas vamos dar uma melhorada nele …
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | public String read(StringBuilder fle, StringBuffer con) { //Opens the file with the name container in the fle parameter File f = new File(fle.toString()); //Create a file reader, then a buffered reader to make our work easier FileReader fr = new FileReader(f); BufferedReader br = new BufferedReader(fr); String lin; //Read each line of the file until it is null while((lin=br.readLine())!=null){ //Put the content read into the buffer pointed by the parameter "con" con.append(lin).append("\n"); } //The caller already have the content, because he created the buffer, but I'll return the string anyway return con.toString(); } |
Mais fácil certo? Bastou ler os comentários, mas o código continua um lixo.
Ou seja, esta é uma gambiarra utilizada por péssimos programadores para contornar a própria limitação de não conseguir escrever um código decente.
Então qual a solução que eu recomendo?
Vamos tentar reescrever este método então:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | public String readFileContents(File fileToRead) { boolean canReadFile = fileToRead.exists(); if(!canReadFile) return ""; StringBuilder buffer = new StringBuilder(); BufferedReader readerForFile = openBufferedReaderForFile(fileToRead); readFileContetIntoBuffer(buffer,readerForFile); closeFileReader(readerForFile); return buffer.toString(); } private BufferedReader openBufferedReaderForFile(File fileToRead){ return new BufferedReader(new FileReader(fileToRead)); } private void readFileContetIntoBuffer(buffer,readerForFile){ String line; while((line=readerForFile.readLine())!=null){ buffer.append(line).append("\n"); } } private void closeFileReader(readerForFile){ readerForFile.close(); } |
Agora se você prestar atenção no nome do método “readFileContents” já vai saber o que o método faz, Além disto, o código do método é quase legível em inglês. A leitura dele ficaria mais ou menos assim:
if not can read file, return null
open Buffered Reader For File: fileToRead
read File Contet Into Buffer: buffer, readerForFile
close File Reader: readerForFile
return buffer.toString();
Ou seja, qualquer um que entenda inglês, como qualquer desenvolvedor tem a obrigação de entender, vai ler o método como se fosse um comentário.
E eu já vi gente fazendo pior do que isto, o código tinha comentários, mas parecia com esta coisa ai em baixo:
1 2 3 4 5 | public String write(StringBuilder fle, StringBuffer con) { File f = new File(fle.toString()); FileReader fr = new FileReader(f); BufferedReader br = new BufferedReader(fr); String lin; while((lin=br.readLine())!=null){ con.append(lin).append("\n"); } return con.toString(); } |
Com certeza tinha muito menos linhas de código do que a minha versão 
Mas não é uma tarefa fácil entender o código que uma criatura destas escreve
Claro que o exemplo que eu apresentei foi um exemplo bem simples, e que escrever código legível requer uma certa prática …
Então, vou fazer uma proposta:
Vou deixar um exemplo de código abaixo, e vocês tentam torna-lo mais legível. Em um ou dois dias eu posto a minha resposta aqui.
Quem quiser pode postar nos comentários o código que escreveu.
Para que o código fique colorido no blog, basta colocar dentro de uma tag <pre lang=”java” line=”1″> … </pre>
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 | package blog; import java.io.BufferedReader; import java.io.File; import java.io.FileNotFoundException; import java.io.FileReader; import java.io.FileWriter; import java.io.IOException; public class VeryBadlyNamedFile { private static final char[] asdfg = new char[] {'I', ' ', 'c', 'a', 'n', ' ', 'd', 'o', ' ', 'v', 'e', 'r', 'y', ' ', 'u', 'g', 'l', 'y', ' ', 'c', 'o', 'd', 'e'}; private String an; private BufferedReader rfsdw; private FileReader temp; public VeryBadlyNamedFile(String an, BufferedReader rfsdw, FileReader temp) { super(); this.an = an; this.rfsdw = rfsdw; this.temp = temp; } public void doIt() throws IOException { ctfiidne(); startDoing(); try { canIDoAnyThing(); } catch (RuntimeException yicdet) { nowReallyDoIt(); } } private void nowReallyDoIt() { firstDoTheOtherThing(); reallyDoItInternal(); } private void firstDoTheOtherThing() { rfsdw = new BufferedReader(temp); } private void reallyDoItInternal() { while (true) { try { imDoingIt(); } catch (Exception e) { break; } } } private void imDoingIt() throws Exception { String s = rfsdw.readLine(); if (s == null) throw new Exception("hahaha, I bet you did not understood the code"); System.out.println(s); } private void ctfiidne() throws IOException { File a = new File(an); if (!a.exists()) { FileWriter wrfedsd = new FileWriter(a); wrfedsd.write(asdfg); wrfedsd.close(); } } private void canIDoAnyThing() { if (new File(an).exists() && new File(an).canRead() && new File(an).canWrite()) throw new RuntimeException(); } private void startDoing() throws FileNotFoundException { File f = new File(an); temp = new FileReader(f); } } |
E agora um “main” só para executar o lixão acima.
1 2 3 4 5 6 7 8 9 | package blog; import java.io.IOException; public class Main { public static void main(String[] args) throws IOException { new VeryBadlyNamedFile("c:\\anyFile.any",null,null).doIt(); } } |
Os exemplos estão em java, mas em qualquer linguagem os comentários para explicar o código servem para mascarar a incapacidade dos programadores escreverem código decente.
PS.: Só para constar, eu não acho de verdade que vocês não devem comentar o código, mas se vocês não escrevem código legível, ou escrevem código que realmente precisa de um comentário para outro programador entender, então vocês não aprenderam a programar ainda!
PS2.: só para constar, o código deste post foi inventado na hora, inspirado em coisas que ja vi em diversos lugares por ai, masescrevi ele direto no blog, então existe uma grande possibilidade de não compilar.
PS3.: acho que preciso de exemplos melhores, mas vocês devem ter entendido a idéia deste post
If you enjoyed this post, make sure you subscribe to my RSS feed!Tags: dicas, livro2, produtividade, refactoring
Reader's Comments
Leave a Comment
Descontão no melhor livro de Rails
O melhor livro de Rails
Licença
Blog do Urubatan by Rodrigo Urubatan Ferreira Jardim is licensed under a Creative Commons Attribution-Share Alike 2.5 Brazil License.
Permissions beyond the scope of this license may be available at http://www.urubatan.com.br/contato/.
Urubatan
Concordo que muitos códigos são auto-explicativos. Mas os comentários ajudam, na minha opinião, a situar principalmente quem não é muito familiar com a sintaxe de uma determinada linguagem. Claro que códigos com um comentário por linha são exagero, mas alguns comentários – nem que seja apenas para destacar a principal ação de um método ou uma validação não trivial de um parâmetro – podem ajudar na compreensão e em uma futura manutenção.
Eu, particularmente, prefiro códigos podres comentados do que códigos sem comentários de quem acha que sabe fazer código compreensível. No primeiro caso, ao menos dá pra ler o que se tentou fazer…
[Translate]
+ sobre comentarios:
– Documente a api publica. Sei q documentacao != comentario, porem sempre vale ressaltar…
– Use nomes significativos, ou de acordo com a semantica e comportamento do pacote/estrutura/operacao/variavel. Isso elimina varios comentarios, como vc mesmo disse…
– Leia e *absorva* os padroes de nomes contidos nos fontes de grandes projetos Open Source, e obviamente o proprio padrao(q eh mais importante q os nomes). Jah existem verbos e palavras a serem utilizados dependendo do caso. Existem varios patterns aplicados com padroes de nomes. Ex.: *Utils, Builders, PropertyEditors, doXxx em template methods… Nao basta mais apenas saber o basico, como eh o caso do uso de camel-case e padrao de nomes para accessors(setters/getters).
– Vc pode fazer um lindo codigo em Basic e um lixo em Lisp. Depende de seu skill e das possibilidades q a linguagem te fornece.
– Construcoes nao claras vao sempre continuar existindo em trechos complexos(principalmente mais proximos da camada baixa de seu software), portanto documentacao ainda vale nesses casos…
Lembre sempre: alem da precisao semantica do nome de seus simbolos, seu nivel de documentacao tb depende da complexidade do fonte(ele continua sendo um algoritmo apesar de tudo) e do skill da equipe q o codifica. Claro q se vc utilizar algum malabarismo de instrumentacao(AOP, proxies dinamicos), ou mesmo uma construcao mais complexa(muitos ainda nao entendem o q eh closure), dependendo de sua equipe tb eh bom documentar…
Att,
JV — julioviegas.com
[Translate]
Na minha opinião, o ideal é a combinação dos dois, código legível e comentários. O segundo pode ser utilizado para explicar uma lógica mais complexa, uma situação diferenciada ou qualquer outra coisa que o código não consiga dizer por si só.
Junte isso com uma boa dose de bom senso e tenho certeza que o resultado será satisfatório.
Abraços!
[Translate]
A combinação perfeita é código bem escrito e testes de unidade!
– isso obviamente não vale se você estiver desenvolvendo algo como um API, como já foi citado
Aí você pode dar adeus aos comentários nos códigos
[Translate]
Não li todo o post mas acho que no primeiro paragrafo você já falou tudo:
“programador hardcore de verdade escreve código legível!”
[Translate]
> “programador hardcore de verdade escreve código legível!”
Sempre eh importante comentario para facilitar o entendimento de um trecho de codigo menos legivel, ou mesmo acelerar a absorcao de um comportamento tanto por parte de sua equipe como pelo autor de tal codigo.
Veja bem, tem codigo q escrevi ha muito tempo atras, entao comentarios bem colocados auxiliam no entendimento de determinados trechos.
Outras vezes utilizamos marcas como TODO(nao feito ainda) ou FIXME(hack ou design mal feito propositalmente) para revisitar mais tarde esses trechos.
O importante eh nao generalizar: se vcs acessarem os fontes do Spring vao ver varios comentarios no core(nao API) q os desenvolvedores deixam para outros desenvolvedores, tornando tal codigo mais acessivel para outros desenvolvedores. Eh o bom senso em acao, como comentou outro colega antes…
Em tempo: Urubatan, acho q o titulo de seu post foi infeliz…
[Translate]
Eu discordo da sua posicao…
Acho que 10% dos programadores atuais conseguem escrever codigos tendo a sua maneira de codificar como meta…
90% escrevem codigos toscos e que sim DEVEM ser comentados…nem que seja para que voce chegue a conclusao que deve apagar o metodo e reescrever…
Quando temos uma equipe… temos que nivelar pelo mais “pobre” do grupo… se pensarmos que todos sao ninjas… podemos ter surpresas no final do projeto…
[Translate]
Dyego, não concordo com o que você escreveu, se os desenvolvedores são ruins, eles são obrigados a melhorar.
Julio, o título não foi infeliz, ele é chamativo de propósito. Este é o primeiro post de uma série sobre refactoring. O próximo deve ser sobre eliminação de código duplicado.
O último vai ser sobre comentar no lugar certo, quando for necessário.
Sempre lembrando que comentário != javadoc
javadoc é documentação de API publica
comentários no contexto deste post, servem para explicar partes do código que os programadores não tiveram tempo ou capacidade de escrever o mais próximo possível da linguagem humana.
os TODO, FIXME, REVIEW não se enquadram nesta categoria na minha opinião, eles servem para gerenciar tarefas ainda não prontas, e só vão passar a ser uma heresia quando forem substituidos por um DONE (tem que bater em quem fizer isto
)
[Translate]
Sao obrigados a melhorar… mas e voce (como gerente de projeto) esta disposto a pagar o preco caso alguns da sua equipe nao facam o melhor ?
[Translate]
> Julio, o título não foi infeliz, ele é chamativo de propósito
Eu continuo achando q eh infeliz, pois comentario nem sempre eh para fracos…
Se fosse assim, os grandes desenvolvedores(nao-fracos) nunca utilizariam eles…
> os TODO, FIXME, REVIEW não se enquadram nesta categoria
> na minha opinião, eles servem para gerenciar tarefas
> ainda não prontas
Perfeito. Porem sao um mecanismo de marcar codigo inline e associar a uma categoria de atividade. Logo, todo mecanismo q nao eh comentario mas precisa referenciar trechos de codigo utilizam comentarios. Eh o caso de javadoc, como vc disse…
[Translate]
O gerente de projetos não tem muito a ver com a legibilidade do código, ele tem a ver com número de bugs criados, corrigidos, reabertos, …
Os colegas de equipe tem a ver com a legibilidde do código
Para assegurar que todos escrevam código decente existe code review, peer programing, …
Programadores júnior não tem a obrigação de ja saber isto, mas vão ter que rever tantas vezes o que foi escrito devido ao code review que vão se acostumar a escrever código legível.
programadores senior que não escrevem código legível não são tão senior assim, ou não estão corretamente motivados
se alguem montar uma equipe 10% com programadores júnior o último problema vai ser a legibilidade do código.
[Translate]
OK , entao o gerente de projeto tá pouco ligando para legibilidade e manutenciabilidade posterior ? Tem certeza ? Voce tem certeza que a equipe sempre vai ser a mesma… a legibilidade é algo que não influi no processo de manutencao ?
[Translate]
gerente de projetos na maior parte das vezes não é um programador, algumas vezes nunca foi um programador. Ele não tem como saber se o código esta legível, exceto se alguem falar para ele que não.
Se alguem disser para ele que o código esta um lixo, ele vai provavelmente dizer que é necessário melhorar isto, e perguntar quanto tempo leva para corrigir.
Se for muito tempo, este gerente deve perguntar por que chegou neste ponto, e dependendo da resposta deve escolher outra equipe para o próximo projeto.
Eu nunca disse que a equipe tem que ser sempre a mesma, o código legível é mais importante ainda se a equipe mudar.
A legibilidade influi sim no processo de manutenção, eu disse que o gerente de projetos, não sendo um programador não tem como avaliar isto, os programadores mais experiêntes da equipe sim tem, e devem durante o code review ou peer programming.
Se um gerente de projeto monta uma equipe só com júniors ele tem mais é que se ferrar mesmo, pois esta foi uma decisão estúpida
[Translate]
Eu acho que voce esta se focando no nome “gerente de projetos” para justificar a sua posicao… troque tudo onde aparece “gerente de projetos” para “responsavel pelo projeto” ou “o cara que vai responder quando levar 6 meses para botar um botãozinho prq ninguem se acha” e coisas do genero…
Infelizmente… comentarios importam sim… e devem ser bem feitos… alem de uma documentacao boa tambem…
Essa estoria de que comentario eh um “desodorante” para passar no codigo e ver se ele cheira melhor não é de toda verdade.
[Translate]
Detalhe , conheco muita gente que programa a ANOS… fazendo coisa que nem junior não faz… entao não transforme os dinossauros em deuses…
[Translate]
Saudações,
Na minha opinião acho que programadores faixa preta, por mais ninja que sejam, gostam de fazer coisa rápidas, boas e fáceis de ser usadas.
Não imagino programadores do google desenvolvendo coisas fantasticas de forma incompreensiveis.
Acho que as coisas tem que ser mais simples possivel, bem organizada e estruturada e, na minha opinião, de fácil manutenção.
Se você se julga um programador forte, que consiga descifrar tudo, em qualquer linguagem sobre qual lógica usada para
resolver um determinado problema, deixo meus parabéns, pois você é o unico.
Trabalho em uma empresa que desenvolve em várias linguagens de programação e há profissionais de alto nivel que, mesmo com vários anos de experiencia (de 15 anos a 20 anos) e consideraveis ceritificações e projetos, vejo perguntando:
“Você tem 1 min ? Estou precisando de ajuda.”
Reveja seus ideais, seu nivel de conhecimento e até onde vai seu conhecimento pois acredito que ao descobrir tudo isso, você mesmo verá que nem ninguém é tão suficiente para não pedir ajuda ou se considerar super forte naquilo que faz.
[Translate]
Acho interessante comentar as regras de negocio no codigo, já que em 90% dos casos não existe documentação. Porém não acho interessante comentar o que cada linha faz, como por exemplo (//Read each line of the file until it is null).
[Translate]
Dyego, também conheço gente que trabalha a muito tempo e não deveria ser considerado senior, a maior parte não para muito tempo em uma empresa boa, ou então não sai por nada de empresas ruins por que sabe que não vai conseguir nada melhor.
Magnata, ninguem esta dizendo que todo mundo tem que saber tudo, isto seria impossível, e todos os programadores que eu conheço pedem ajuda para os colegas (quem disser que nunca faz isto é mentiroso).
Mas continuo dizendo que é obrigação de qualquer programador escrever código legível.
é um exemplo de código muito difícil de alguem bater o olho e entender. Alguem preocupado com a qualidade do código deve criar regras impedindo que isto seja escrito. e o peer review ou pair programming são formas de reforçar estas regras.
Se vocês não sabem como isto poderia ser reescrito, um possível exemplo seria:
E sim, eu estou afirmando que se alguem esta preocupado com a manutenibilidade do código, tem que obrigar ou pelo menos recomendar fortemente que regras que levem a um código mais legível sejam seguidas.
Por exemplo:
- não é permitida a criação de variáveis e métodos com nomes de apenas uma letra
- nomes de variáveis e métodos precisam ser significativos
- não é permitida a utilização direta de multiplas condições compostas aninhadas, elas devem ser quebradas em variáveis ou métodos com nomes significativos
Se estas regras não existirem, é por que o tal “responsável” não esta mesmo preocupado com a manutenibilidade do projeto.
[Translate]
@Magnata
Muito bem colocado! +1
[Translate]
É fácil falar que não é necessário comentar código fonte quando se faz sistemas simples ou que você sempre será o ‘dono’ ou ainda achando que ninguém mais vai colocar a mão nele. Pensado que você trabalha numa grande empresa, em que existem vários sistemas, sistemas que podem gerar prejuízo alto, no caso de alguma falha, e que ainda várias pessoas podem manter ele. É difícil engolir a idéia de que o comentário é inútil. Imagine que o sistema está com um bug em produção é preciso resolver em uma hora, não foi você que desenvolveu. Você tem que identificar e corrigir o problema, o que será mais fácil?? Com comentários ou sem comentários?
Acho que devemos entender é que cada ser humano pensa de uma forma diferente (ainda bem), cada um escreve de uma forma diferente e também programa de forma dieferente. O comentário facilita para o próprio desenvolvedor em suas manutenções, nunca será um problema. Problema será se não tiver comentários. Independente da clareza do código.
Você pode achar que é o melhor programador do mundo, que fez um código lindo, mas outra pessoa que irá manter seu pode não entender o seu código por vários motivos.
Não concordo com o artigo.
[Translate]
Só mais um detalhe. Concordo plenamente com o Magnata. Não existe ninguém bom demais que não precisa de ajuda em algum sistema desconhecido.
Seja humilde.
[Translate]
Ainda acho que comentários são necessários e isso não impede de fazer código legível. Fora que é muito mais fácil escrever um programa que remova comentários de código do que fazer um que comente. =D
[Translate]
Boa noite!
Pessoal,
Analise o nome do post:
Comentário no código é para os FRACOS.
e sua descrição.
Muito bem, ele não diz dizer que os FRACOS são profissionais com baixa capacidade e sim FRACOS em relação a facilidade de ver o código escrito.
Então não generalizem.
[Translate]
Código legivel é fundamental, mas este foi um exemplo básico. Quando se cria algoritimos e etc, ou algo mais complexo… um comentário é fundamental para entender a lógica por trás.
[Translate]
No livro de refatoração do Fowler que o Urubatan citou, mais especificamente na página 80 ele diz o seguinte:
“Não se preocupe, não estamos dizendo que as pessoas não devem escrever comentários. Na nossa analogia olfativa, cometários não são cheiros ruins. Na verdade eles são um cheiro doce. A razão pela qual mencionamos os comentários aqui é que eles muitas vezes são usados como desodorante. É surpreendente a frequência com que você vê um código cheio de comentários e percebe que eles estão lá porque o código é ruim.”
Eu particularmente concordo com o Urubatan, toda vez que penso em escrever um comentário, procuro refatorar o código de modo que o comentário não seja necessário. Mas isso vai de cada um, isso é assunto que gera muita discussão e não se chega a lugar algum.
[Translate]
Pois é, fácil escrever para máquinas comparado a escrever para humanos.
[Translate]
Comentário em código fonte ajuda a poluir o software. Métodos que são genéricos onde tudo se faz em único local, é o reflexo do imaturidade e desconhecimento de metodologias de desenvolvimento de software. O resultado de um código com muito comentário é o alto custo de manutenção, pois nem sempre o método faz exatamente o que seu nome sugere demandando tempo para verificar seus comentários e o próprio método.
[Translate]
Aêêê Urubatan, arranjou sarna pra se coçar, hein?
huahauhauauahuha
Minha opinião?
- Bons programadores escrevem código legível e auto-explicável;
- Bons programadores escrevem comentários somente onde eles realmente se fazem necessários.
Agora, onde eles realmente se fazem necessários?
1º) No javadoc (mas não é caso do seu post, como você mesmo disse);
2º) Comentar uma regra de negócio que talvez não seja tão trivial de entender, delimitar pequenos contextos, e coisas do genero.
Como diz o ditado: Nem tanto céu, nem tanto terra!
Mas, em linhas gerais, concordo com seu post sim, com certeza.
“Comentário não pode ser usado para remediar código ruim”
Abraço!
(Jabázinho: http://codezone.wordpress.com/2008/02/08/refatorar-e-preciso)
[Translate]
Concordo que normalmente um código bem escrito não precisa de comentários. Mas, como eu disse, normalmente.
Tenho experiência em apenas 3 tipos de programação: a programação de fundo de quintal, fazendo sistemas comerciais e em programação científica. No primeiro caso, eu faço de qualquer jeito mesmo, pois é um produto pra mim. No segundo caso acho que se aplica a questão do código bem escrito. No terceiro caso, por mais que o código seja bem escrito, normalmente ele deve também ser bem otimizado. E aí meu caro, se não tiver comentários…. Não precisa comentar linha por linha, mas separar um bloco de código e escreve um pequeno comentário em cima ajuda muito. Um comentário simples, do tipo: “Algoritmo YYYY. Fonte: artigo publicado no XXXX”
Era isso.
http://demoniodemaxwell.wordpress.com/
[Translate]
No meu caso, em toda minha vida tive que trabalhar com programação em 3 cenários:
1 – Em casa. Nesse caso eu faço de qualquer jeito, afinal de contas é pra mim mesmo, eu me entendo. Não vou perder tempo documentando, criando trocentos métodos para meus testes;
2 – Numa equipe no trabalho. Aqui eu concordo com você. Código bom é legível por si só.
3 – Programação científica. Por mais que você faça direitinho, aqui normalmente você usa algoritmos complicados e/ou tem que otimizar o código. E nesse caso, acho que não custa nada você seprar um bloco de códigos e fazer um comentário em cima. Um comentário simples do tipo: “Algoritmo XXXXX publicado no livro/artigo YYYY”
Era isso.
http://demoniodemaxwell.wordpress.com/
[Translate]
Só um comentario, de acordo com qualidade de codigo (pode ser da SUN ou checkstyle e PMD) não seria muito legal usar dois returns no mesmo método. Você quando se considera como uns dos melhores programadores do pais (como diz em seu about), o que acha disso?
public String readFileContents(File fileToRead) {
boolean canReadFile = fileToRead.exists();
if(!canReadFile)
return “”;
StringBuilder buffer = new StringBuilder();
BufferedReader readerForFile = openBufferedReaderForFile(fileToRead);
readFileContetIntoBuffer(buffer,readerForFile);
closeFileReader(readerForFile);
return buffer.toString();
}
[Translate]
taí uma coisa que quase ninguém lembra de fazer no codigo: usar métodos privados para dividir a lógica de uma forma mais… lógica (duh!). Tirando algumas excessões, acho que métodos devem ser pequenos pedaços inteligiveis de código que não deveria ter mais que 30 linhas (ex.). Assim o programador está se obrigando a adicionar maior semantica ao código e possibilitando uma maior vida ao código escrito. Levante a mão quem já pegou código de manutenção e deu um ‘refactoring do mal’, ou seja, apagou todo o código e escreveu tudo de novo pq não conseguia entender bulhufas entre métodos e variaveis com nomes malucos e sem sentido.
Outra coisa sobre tamanho de métodos: isso é uma prática recomendada por ferramentadas de analise automatizada de código, como pmd ou firebug!
Jornal Java
[Translate]
Muito Xiita…
Dependendo, comentários são ótimos.
Basta não parafrasear o código como no exemplo…
[Translate]
Discordo que bons programas não precisam de comentários. Eles precsam sim, especialmente para explicar o funcionamento em mais alto-nível ou como usá-lo (como a API, javadoc, o algoritmo usado ou use-cases, por exemplo).
O seu exemplo também não foi muito bom. Criar diversas mini-funções para deixar mais legível tem, na verdade, o efeito oposto. Para entender o que está acontecendo vc tem que rastrear cada função.
Ser muito prolixo também é um problem. Usar “ToRead” em “FileToRead”, “Content” em “FileContent” são redundantes e devem ser evitados pra deixar o código mais limpo.
Outros problemas são:
– Testar a existência do arquivo não é o mesmo que poder lê-lo.
– Usar a palavra “Buffer” para o StringBuilder é confuso, especialmente considerando que existe uma classe chamada Buffer e estamos usando um BufferedReader.
Creio que o exemplo abaixo é mais limpo, correto e legível:
public String readFile(File file) {
StringBuilder content = new StringBuilder();
Reader reader = new BufferedReader(new FileReader(file));
try {
String line;
while((line=readerForFile.readLine()) != null) {
// readline() drops the end-of-line, so we append it here.
content.append(line).append(“\n”);
}
} catch (IOException e) {
return “”;
} finally {
reader.close();
}
return content.toString();
}
[Translate]
Vinicius, quando você utiliza um monte de mini-funções, você não tem que rastrear cada função porque o nome dela ja deveria indicar o que esta realizando. Claro que o nome da função poderia deixar muito a desejar, mas a ideia não é essa.
[Translate]
Tamanho da funcao, estrutura de dados, etc, nao importa… O importante eh aplicar o principio da coesao e a qualidade sistemica conhecida como extensibilidade. Sugiro esses topicos basicos quando o assunto eh qualidade do fonte.
[Translate]
Essa de criar várias expressões e depois usa-las no if é comum mesmo?? Nunca tinha visto nada parecido, mas devo dizer que fica mais claro do que colocar todas as condições no if e fazer aquele monte de parênteses.
[Translate]
Excelente! Sem comentários.
[Translate]
Bom código é claro mas comentário não é SEMPRE dispensável. Tem horas que faz bem, principalmente em coisas não tão óbvias.
Exemplo de código bem escrito e auto-explicativo é o fonte do plan 9.
[Translate]
comentários dizendo o que o código faz sempre são ruins, se eles são necessários é por que o código foi escrito por um programador dislexico.
Comentários dizendo por que o código faz alguma coisa são bons
[Translate]
Comentário explicando como se abre um arquivo é uma coisa, explicando por que um determinado trecho ou uma determinada lógica foram implementados é outra…
[Translate]
[...] com a seqüência de posts com títulos polêmicos que comecei dizendo que “Comentário no código é para os fracos“, segue um curso básico de refactoring para quem é pobre (por que vou utilizar o eclipse [...]
[Translate]
PS.: Só para constar, eu não acho de verdade que vocês não devem comentar o código, mas se vocês não escrevem código legível, ou escrevem código que realmente precisa de um comentário para outro programador entender, então vocês não aprenderam a programar ainda!
a ver seus comentários, está confirmado: NINGUÉM LÊ OS PS!
Excelente post! xD Eu busco fazer os dois. Se eu tenho de comentar coisas banais de código eu sei que estou fazendo coisa errada. Mas se é para colocar regras de negócio, eu vou em frente xD
[Translate]
Acho zuado escrever métodos com mais de um return.
[Translate]
Eu acho que temos uma confusão grande entre codigo de infra estrutura e codigo de dominio(regras de negocio). Codigo para ler um arquivo não e necessário comentar agora código, porém onde uma regra de domínio e aplicada o código pode e dever ser comentado.
[Translate]
Cara, entendi a idéia.
Mas voce misturou qualidade de código com comentários e uma coisa não está intimamente ligada a outra.
Se o código é ruim, isso é um problema independente do que está escrito nos comentários.
Se o código é bom, os comentários podem acrescentar algo, quando necessário.
Voce montou uma argumentação inadequada para sustentar tua tese.
Vinicius
[Translate]
na verdade eu não concordo que sejam coisas independentes, claro que código bom pode ter comentários, mas a maior parte usa comentário para contornar um código podre …
[Translate]
concordo que sempre é bom ter menos linhas de código, e sobretudo, um código mais compreensível, mas é um tanto exagerado achar que código bom é aquele que não tem comentário nenhum. Comentários podem ser muito úteis sim, até para o programador que escreve do jeito mais claro possivel. Quer um exemplo? Imagine um codigo que retorne uma data em formato UNIX_TIME, algo como:
ctime: 123490283
Qualquer programador vai precisar de uma bola de cristal pra adivinhar que data é essa, e pra nao obrigar ninguem a ter que converter o numero só pra descobrir, não custa nada colocar um pequeno comentario informado qual é a data que o numero representa…
[Translate]
eu nunca disse que código bom é aquele que não tem comentário, disse que é aquele que não precisa de comentários
[Translate]
Exemplos simples e pequenos assim são sempre fáceis de tornar legíveis, mas na prática, no desenvolvimento de um sistema real completo, isso numca é possível de ser aplicado 100%.
Para mim tem que existir um bom senso. Utilizar códigos legíveis onde for possível, comentar onde for necessário.
Comentário no código é para os fracos ?
Eu diria: “Código sem comentário é de programador preguiçoso.”
[Translate]
[editado pelo dono do blog]
Rafael, eu sei que não são comuns equipes formadas apenas por profissionais muito experientes, sei que escrever código legível é difícil, sei que comentários deveriam ser utilizados para dizer por que o código foi escrito e não o que o código faz.
Tudo bem que tu não tenha capacidade de escrever código legível, mas tu deveria ter pelo menos prestado atenção no texto todo para entender que este texto é uma critica a quem tenta usar comentários para dizer “o que o código faz”, isto é errado, comentários devem ser utilizados apenas para dizer “por que o código faz alguma coisa desta forma”.
PS.: não gosto de publicar comentários me chingando no meu blog, principalmente se escritos por alguem que não leu o post todo
[/editado pelo dono do blog]
[Translate]
É bem verdade que escrever um código legível é, ou deveria ser, o objetivo de todo e qualquer bom Desenvolvedor. Porém, nem sempre conseguimos escrever um bom código logo de primeira.
Sendo assim, escrever comentários no código é algo bastante importante (e sensato) principalmente para posterior refactoring.
Não consigo imaginar uma justificativa plausível para não escrevermos comentários em nossos códigos, afinal de contas, nunca sabemos quem irá manter o código que escrevemos… enfim.
Nos próprios códigos de exemplo no seu post, certamente ficou mais fácil de entender o código, que continuava um lixo – como vc mesmo colocou – mas como existiam comentários, o refactoring no código será bem mais tranquilo de ser feito…
Porém concordo que comentário pra tudo é desnecessário e às vezes prejudicial até, mas até mesmo a experiência em comentar irá servir para criar comentários mais úteis ao longo da carreira de qualquer Desenvolvedor.
sendo assim, documentar e comentar o código é válido e necessário, sempre.
[Translate]