Código bem comentado

Publicado em 02/02/2012 09:30 230 Comentários

Quer comprar essa camiseta?

/* História real enviada por Andre Luiz */
Programador: Cara, esse código que você fez não tem um comentário… Você tem que comentar para ficar mais fácil de entender os mistérios que passam pela sua cabeça…
Alonso: Tá… Vou comentar, depois te passo…
Depois…
Alonso: Pronto, tudo comentado!
No computador:

/* Agora, vou dar um printf */
printf (...);

Programador: FACEPALM!

Tag: , , ,

Categorizados em:

230 Comentários

  • louis disse:

    Mais comum do que possa parecer…
    uma vez peguei um código que comentaram o chinês feito sobre o algoritmo…

  • Alexandre Di Salvo disse:

    Já vi muito essa cena hahaah

  • Felipe Aron disse:

    Melhor mesmo é quando encontra algo do tipo (verídico):
    “.. não mexa uma linha sequer, se não vai dar pau!”

  • Dah Espindola disse:

    Por essa, o Alonso merece o troféu Capivara Humana Gold Plus. Tomara que ele não comente os comentários também.

  • Felipe Aron disse:

    Outra melhor ainda é (verídico):

    if (….) then
    begin
    /* nada a fazer… */
    end
    else
    begin
    … código….
    end

    • Willian disse:

      Lógica by Alonso, com direito a comentário /* … */ numa linha só… rsrs

      • /dev/random disse:

        Opa, comentario /* … */ é padrão ANSI viu :P

        • Bardes disse:

          os comentários com “/**/” são (originalmente) o único método de se comentar em C. Em C++ ambos modos (o “//” e o anterior) são aceitos, sendo as barras mais recomendadas para comentários pequenos ou para comentar linhas de código, já que não causam problemas mesmo quando se comenta uma linha que já tinha um comentário antes…

    • Heitor Silva disse:

      Já peguei isso várias vezes…

      fora quando eu pegava os //todo dentro de IF
      Oo

    • Linconl disse:

      Padrão “Else forever”

    • Azarias disse:

      Olha da última vez que vi isso, retirei do código e a porra de pau, voltei o maldito e funcionou de boas… vai entender.

      Isso sem contar as variáveis que mudam de valor do nada e assim que vc comenta alguma coisa o erro some…

      • Mago disse:

        Voce nao tá falando sério….

      • Phill disse:

        Já passei um problema parecido… Depois de muito tempo tentando encontrar um erro no programa, resolvi colocar um print pra ver onde o programa estava, foi o seguinte print:
        printf(“Puta que pariu”);

        Misteriosamente o programa funcionou nessa hora… Depois dessa eu tive que rir.

        Mas por fim achei o erro e corrigi o código

        • Anonimo disse:

          Vc estava usando o dev-cpp ?? Pq ele realmente tem muito bug.

          Varias vezes eu trocava:

          int i;
          int j;

          por

          int j;
          int i;

          E o codigo começava a funcionar. Inspecionando o assembly do programa gerado, era assustador as bizarrices do codigo gerado por ele. Não sei q versão do gcc q eles compilaram lah, mas eh muuuuito tosca.

          • @wbarbosa_ disse:

            Isso tá com cara de que em algum momento o programa está gravando algo onde não deveria e ao se trocar as vars de posição trocou-se os endereços delas e a gravação em local errado não surte mais o efeito colateral visto anteriormente…

            Já alonsei muito assim.

    • Davi Cardoso disse:

      Já vi um amigo precisar fazer um comentário exatamente igual a esse. Meus colegas e eu rimos muito enquanto questionávamos o fato de que o programa não funcionava direito caso o IF inútil fosse removido. Não tive tempo de avaliar a lógica aplicada ao programa, então, até hoje aquilo é um mistério pra mim! #CiênciasOcultasDaComputação

  • Abraão Alves disse:

    (Comentário no sourceCode é a confirmação de um codigo não expressivo.)

    Por essa e por outras:
    Sem comentário.

    • Fernando disse:

      Se eu pudesse dava 1000 up votes! mas te prepara que vc vai levar 1000 para baixo, da galera que acha que comentário substitui código bem escrito.

      • Acho que qualquer programador maduro sabe que comentário não substitui um código bem escrito. Assim como quero acreditar que qualquer programador maduro sabe que nada substitui um código bem documentado já nos próprios comentários.

        Hipóteses assumidas por uma função/classe, suas restrições, como utilizar uma função são exemplos de comentários que deviam estar presentes num código fonte.

        É claro que alguns, por inexperiência acham que um código bem documentado é parafrasear o mesmo em portugol.

        • O comentário do Renato está muito correto em enfatizar a importancia dos comentários bem estruturados, principalmente em lembrar que comentários fazem parte da documentação do projeto, que pode ser requisitado pelo cliente em alguns projetos, como ja conteceu em um projeto que trabalhei, e consequentemente isso é pago pelo cliente, então um bom comentário é tao necessário quanto um bom código.

      • Aramati_ disse:

        Alguem me disse uma vez que a documentação começa pela variáveis autoexplicativas e código legível.

        Nesse ponto de vista então pode-se dizer que -> Um codigo muito claro e legível já pode ser considerado um código comentado.

        • Cristiano Steffens disse:

          Recomendo Clean Code do Uncle Bob, um dos melhores livros sobre qualidade de software que já lí até hoje.
          “A qualidade é o resultado de 1 milhão de atos altruístas de importar-se.”

      • Depende, as vezes um comentário bom para um código porco faz o programador reduzir o calhamaço de lixo em duas linhas de fácil compreensão.

    • Raphael disse:

      Quero ver vc dando manutenção em um código de mais de 1000 linhas sem comentário nenhum….

      • Fernando disse:

        1000 linhas? se vc tem um arquivo desse tamanho, meu amigo, não são comentários que vão te ajudar.

        • louis disse:

          já peguei uma classe de 52000 linhas pra dar suporte.
          Haja coração amigos!

        • Ei, o mundo real não é como o mundo da fantasia das faculdades.

          • Azarias disse:

            no mundo real a gambiarra impera e não é só na programação não.

          • Fernando disse:

            Sim, na faculdade vc pode fazer o seu trabalho criando tudo num grande arquivo ou um método de 600 linhas que ninguém vai se importar. Talvez seu professor de OO te chame a atenção.

            Fazer isso é porquice. É não se preocupar com o que faz e usar o tempo e a pressão como desculpas para a sua limitação. Onde trabalho, todas as classes grandes são refatoradas. Se alguém tem dificuldade de entender a importância disso, vai fazer pair programming com outra pessoa. Mas normalmente, pessoas assim nem são contratadas.

          • Werner disse:

            @Fernando, por mais que eu queira concordar com vc, infelizmente (MESMO) sou obrigado a dizer que na vida real, não só essas pessoas são contratadas aos montes, como elas muitas vezes acabam virando o ‘chefe’. Eu já vi isso acontecer mais vezes do q gostaria de ter visto.

            Ou então eu andei trabalhando nas empresas erradas (o que tbm é verdade de certa forma).

            Quanto à forma de se trabalhar, eu concordo contigo em 100%.

        • Victor Hugo disse:

          Nem todos os objetos só debitam ou creditam na conta corrente. Tem objetos que têm vários comportamentos e isso é natural. A OOP serve para modelar o comportamento de um processo/sistema mais próximo de como o vemos no mundo real, mas tem gente que ainda não compreendeu isso. Se o objeto tiver 1000 comportamentos vai fazer o que?

        • Kaiel disse:

          Tive um gerência que dizia que se você precisar rolar a tela mais de duas vezes para ver o código de um método, então ele deve ser dividido.

          • Werner disse:

            Isso não saiu da cabeça da sua gerência, pode crer.
            Isso é lei. Uma pena que ela seja mais ignorada do que seguida.

          • Victor Hugo disse:

            … rolar duas vezes… Anotado!
            … comprar monitor grande não para deixar o código menos intuitivo… Anotado!

      • Luís Henrique disse:

        dá uma lida nisso aqui para você entender o espírito da coisa, Raphael http://blog.fragmental.com.br/2007/12/28/expressividade-no-codigo/

      • Rafael disse:

        Se vc precisa de um comentario para dizer oq um codigo faz é a maior prova de que ele está mal escrito!

        • Felipe Q. B. disse:

          Se você dispensa comentários em código é sinal de que não trabalha em uma empresa com mais de 1 programador. Falou uma baita besteira aí! hehe

        • Anderson disse:

          putz… comentários são mto importantes… ou vai falar que “o seu próprio código se explica” ? já ouvi essa…

          Se tiver 2 programadores no mesmo projeto, já é impossível sobreviver sem comentários…

        • Aramati_ disse:

          Funções pequenas essas hein ¬¬

        • É velho, concordo com os rapazes acima. Mesmo códigos muito bem escritos às vezes são complicados de entender sua lógica. Neste caso os comentários ajudam pacas.

        • Raphael disse:

          O codigo pode estar bem escrito, mas se a lógica for muito extensa é melhor explicar /*Começa aqui o cadastro do cliente*/ do que ter que ler todo o codigo e descobrir que não é esse trecho que vc procurava

        • Fábio Martinazzo disse:

          Eu concordo em partes…

          Às vezes você terá que fazer algo no código que foge completamente do padrão que a aplicação vinha tendo desde então… esse é o típico cenário que se exige comentários.

          Entretanto, um código bem modularizado e arquiteturado não exige tantos comentários dentro deste. O que se exige é uma documentação explicando como estão divididas as camadas da aplicação bem como bem estipuladas suas respectivas funções…

          Aqui na empresa, temos bem especificada a camada de regras de negócio da empresa contratante, aonde vai as regras como.. ao criar um projeto, gerar n contas a receber nos próximos meses, de acordo com os parâmetros.

          Isso já está dividido na aplicação em uma classe estática (criada só pra modularizar) em um namespace só pra essas classes (os de regras de negócio da aplicação). O nome das funções são específicos, e estas são curtas. Caso a função começa a ter mais escopos (agora além de gerar contas a receber, também já irá dar baixa nessas contas) então chamamos outra função pra esse fim específico:

          public static bool geraContasAReceberPorProjeto(ref Projeto objProjeto)
          {
          //Codigo
          if (!geraPagamentosContasPorContaAReceber(ref Conta objContaReceber))
          return false;

          if (!outraFuncaoQqr(ref TipoQqr outroParamQqr))
          return false;

          return true;
          }

          Uma vez recebemos uma palestra em uma empresa que eu trabalhava que focava nisso… em vez de um código cheio de comentários, um código bem modularizado é o que se espera em uma nova geração de softwares…

          Claro que passando pra uma realidade de mercado (manutenção de projetos antigos) isso é bastante inviável.. a menos que se reescreva quase todo o código…

          Aqui a empresa consegue trabalhar dessa forma, porque criamos vários projetos recentemente.

      • Marcos Sartori disse:

        É mil vezes pior, a sensação te um comentário no meio do código é a mesma de alguem te chamar enquanto tu ta programando, te interrompe e tu leva uma meia hora para voltar para onde tu tava…

    • Luís Henrique disse:

      issae

    • Jeferson disse:

      Humrum, todo mundo tem q adivinhar toda a sua logica de raciocinio ne? Por melhor q seja o código, se ele tiver muitas linhas, ter q ler e reler pra saber o q vc quis fazer é no minimo uma grande perda de tempo, que pode ser economizado com pequenos comentarios inteligentes.

    • /dev/random disse:

      Ah é? Descobre o que faz isso aqui então (e tente descobrir os comentários originais deste código hahaha):

      i = * ( long * ) &y;
      i = 0x5f3759df – ( i >> 1 );
      y = * ( float * ) &i;

      Te garanto que esse código é BEEEEM expressivo.

      +1000 pra que souber :)

      • Pro John Carmack deve ser bem expressivo. :)

      • Cussuol disse:

        Estamos falando de código expressivo.
        E o primeiro passo para um código ficar expressivo é da bons nomes para as variáveis, classes, métodos, etc…..
        No seu exemplo i e y não significam nada. Logo, é impossivel olhar para esse código e dizer o que ele faz.
        Exemplo:
        getSomaSalariosPorDepartamento(codDepartamento)
        Ele poderia ter o comentário:
        // Obtem a soma do salarios dos funcionarios de um departamento, informe o código do departamento como parâmetro.

        Mas sinceramente, precisa disso?
        Precisaria se alguem tivesse programado assim:
        getSoma(cod)

        O que sinceramente é muito comum. Tem programador que acha vantagem colocar nomes com duas ou tres letras para “digitar pouco”, e f… com todo mundo.

        • Hay disse:

          O código acima não é tão simples assim. Se quiser entender melhor: http://en.wikipedia.org/wiki/Fast_inverse_square_root

          Depois, explique para mim quais nomes de variáveis você utilizaria.

          • /dev/random disse:

            o cerne do código são essas 3 linhas, que dão a aproximação inicial do resultado. As outras linhas são iterações do método de newton para refinar o resultado.

        • Evandro Oliveira disse:

          Impossível não é não, parceirinho. Posso te garantir.
          E nome de variável coeso não explica lógica, explica valor.

          No mais, deixo com vocês uma máxima que levo como um mantra:

          “Uma m… de código bem documentado, continua sendo uma m…
          Um bom código sem documentação te faz pensar antes de utilizar
          Um bom código bem documentado salva tempo, vidas e empregos”

          O objetivo é você não ter que se aventurar no source pra entender qual será a saída do valor inputado.

          Acho que ninguém aqui discorda que o source do PHP seja mal escrito, ou tem? Ainda assim preferimos recorrer à documentação do que ao fonte.

        • Rafael disse:

          Disse tudo, isso é um código muito bem escrito e por si só não são necessários. Quanto aos zés que falam que uma classe com quinhentas mil linhas é preciso comentar, aí já está errado, a classe está fazendo mais do que devia. Princípio da responsabilidade única, o que poucos devem saber por aqui.

          • Victor Hugo disse:

            Ahhh… agora entendi! Responsabilidade única é fazer coisas em poucos métodos pequenos…

            E eu que achava que responsabilidade única era outra coisa…

      • Albaney Baylão disse:

        O código está mal escrito.

        Bastava criar a seguinte função :
        float FastSquareRoot(float y)
        {
        i = * ( long * ) &y;
        i = 0x5f3759df – ( i >> 1 );
        return * ( float * ) &i;
        }

        Pode não entender a matemática, mas o código é cristalino.

  • Jonathan disse:

    Que tal esse:
    /*A regra é clara! Quatro espaços para identação, nada de usar Tab. Merecia uma advertência. É com você, Galvão. */

  • lipelandim disse:

    Pior quando vc vai fazer manutenção no sistema e tem um comentário assim.

    // solicitação do Cliente

    • louis disse:

      e me diz qual parte do código não é solicitação do cliente?

      • flavio disse:

        vá me desculpar, mas quando mandam eu fazer alguma coisa estupida e eu tenho que obedecer eu deixo o comentário “fazendo xyz devido a solicitação de fulano (gerente fulano, ou diretor fulano ou fulano da empresa abc, cliente… algo assim)”.

        Ja vivi o suficiente nesse ambiente de desenvolvimento para ver N vezes um projeto caindo no colo de neguinho que não está sabendo de nada, encontrar algo bizarro implementado e ai a culpa cair no ultimo que mexeu nisso, enquanto essa pessoa só obedeceu ordens, não é culpado…

        • Hay disse:

          Ok, mas nesse caso você deixou explícito que foi solicitação de uma pessoa específica. Talvez seja interessante deixar esses comentários para o controle de código-fonte, mas enfim…

          Uma coisa é você colocar um comentário:
          // Caso especial de desconto permanente definido por
          // Fulano de Tal, para produtos da categoria XYZ. O
          // valor do produto em si não pode ser alterado pois
          // a tributação incide sobre o valor antes do desconto
          ou
          // Desconto especial – ver informações a respeito no ticket 99999

          Outra coisa é:
          // Caso especial de desconto definido pelo cliente

          • flavio disse:

            concordo que o segundo comentário ficou genérico o suficiente para ser inútil…

            quanto a o lugar desse comentário ser no controle de versão, eu francamente nunca vi individuo nenhum procurar em qual commit que colocaram determinada parte de um código para falar/fazer alguma coisa dela, especialmente para falar mal…

            num mundo ideal assim seria melhor mas na prática, no mundo real é melhor deixar certas coisas mais “visíveis”.

          • /dev/random disse:

            @flavio,

            svn blame é seu melhor amigo.

        • Fábio Martinazzo disse:

          É o que mais dá.. =D Uma vez meu chefe ficou emputecido pq eu escrevi no código:

          //Fulano mandou retirar a linha a seguir:

          Adivinha o que aconteceu? Deu pau no cliente e ele leu o código… foi muito irado esse dia!! =P

  • Lisangelo disse:

    Melhor seria se colocasse um /* na primeira linha e um */ na ultima.

  • Pior é aqueles:

    /* não sei como funcionou, não mexa! */

  • …. aposto que nunca encontraram assim …
    /* que deus me ajude neste programação */
    /*testando essa linha*/……….

  • Fabian Ribeiro disse:

    Tão ruim quanto não comentar é usar nome de campos e/ou variáveis que não dizem nada do que se trata tipo:

    m_c_cliente

    m de que?
    c é o que?

  • Danilo disse:

    O melhor é esse:
    /*
    * Antes, Deus e eu sabíamos o que esse código fazia.
    * Agora só Deus sabe.
    */

  • Raphael disse:

    /*
    * Inicia o gato chinês
    * Se False, x = 1. Se True, x = 1 também
    */

  • blah disse:

    hahaha, mas é massa encontrar comentários engraçados no meio do codigo…

    pior é não encontrar nada…

  • Marcos Sartori disse:

    Comentários para que? A linguagem C já limpa, bonita, simples e livre de ambiguidade. É só ler o código!

    Sinceramente, sempre que eu pego um código que não é meu e ele esta comentado, a primeira coisa que eu faço é ocultar os comentários no emacs, por que fica horrível de ler o código com aqueles Snippets interrompendo a leitura no meio, atrapalhando a identação e forçando teu cérebro a voltar para o processamento de linguagem natural enquanto tu tava rodando o algorithmo mentalmente.

    • :( disse:

      {Respondendo um post idiota}
      Falou o cara que compila tudo na mente!
      {espero que não oculte o comentário do meu comentário também}

    • Cussuol disse:

      Eu descordo de você quando o trecho de código é grande e complexo, justifica colocar um cabeçalho explicando o que ele faz. Pelo menos ajuda o mantenedor ter que ler a p..toda para tentar entender.
      Vai me dizer que você nunca usou o INDICE de uma publicação para evitar ter que ler ela inteira?

      • Marcos Sartori disse:

        São coisas completamente diferentes e o análogo ao índice no código é o cabeçalho…

        Não sei para o nível que tu programa, mas para o nível que eu estou acostumado a programar. É muito mais fácil pegar e ler o VHDL da plataforma do que procurar na documentação.

        Portei um RTOS para a nossa plataforma virtualizada recentemente, e era muito mais simples ler as rotinas em assembly e C, procurar onde elas eram chamadas, rastrear os cenários que cada rotina aconteceria do que ler os comentários.

        Recentemente por pressão do chefe, comecei a usar doxygen nos meus códigos, deus do céu, que coisa horrível de poluída. E muitas vezes tu nem sabe o que dizer para a função, assim como muitas vezes não sabemos como nomear um variável ou função e acabamos com nomes tipo a, x,s , doTheWalk.

        Ainda bem que não trabalho com Java, morreria de fome…

    • Gustavo disse:

      com certeza vc nunca viu uma lógica mais complicada então. Por mais que o código esteja limpo e bem escrito e vc seja “mt bom”, existem lógicas absurdas que não são fáceis de entender só lendo o código. Nestes casos o único jeito para se entender seria fazendo um teste de mesa (simulação) para entender a lógica. Concorda que se a estivesse comentado seria mais fácil???

  • Nícolas Fernandes disse:

    /* Aqui é uma gambiarra pra ver se funciona esse código pra entregar para o cliente… */

  • Nicholas disse:

    Já coisas do tipo:

    //Agora, esse cara vai verificar a veracidade da variável $tal;

    ou

    /**
    * Essa função ser executada.
    **/

    hauSHUAShuasuhashuahsuhasuhuashuasHUashuASHUhuashuasuhsahu é da hora ver comentários nos códigos… revela MTO sobre o programador que fez

  • Luiz Eduardo disse:

    Pow já peguei um caso sinistro
    /*
    * Área Sagrada, não alterar
    */
    Vc tirava o comentário o programa dava pau. Parece mentira, mas eu vi!

  • Felipe Aron disse:

    Lembrei de outra que quase me fez perder o almoço pela boca:

    x := 1;
    if (x 1) then
    begin

    end

  • Bitetti disse:

    /*
    * Eu evoco os poderes da
    * SUPER VACA
    */

  • Leandro Passos disse:

    E já vi na faculdade, o seguinte: projeto de sistema, analiso o código, os comentários estão abarrotados de palavras de baixo calão, como se o noobie desenvolvedor se sentisse obrigado a entender o que estava escrito, por bem ou por mal. Se ele fosse trabalhar comigo ele estaria f*****.

  • Rafael Duarte disse:

    /* Um comentário vale mais do que mil documentações */

  • Felipe Aron disse:

    faltou o código “diferente” no IF … não aceitou aqui

    if (x 1) then…

  • Willian Duarte disse:

    Eu acredito no código legível por si só. Se o código precisa de comentários para ser compreendido, ou o código esta mal escrito, ou a linguagem não permite um código limpo, ou quem está lendo precisa de mais estudo.

    Já li que o comentário em código é a tentativa do programador se redimir com o próximo que pegará aquele código, deixando sua consciência limpa (ou quase). kkkkkk

    • blah disse:

      não é tão simples um código legivel universal, pois existe simples coisas que alteram de forma dramática da lógica a sua, o que não quer dizer que seja não legivel, mas para o criador e muitos outros sim, mas para você e muitos outros não.

      É claro que os comentários ajudam deixando a consciência limpa, pois você está sendo gentil e detalhando o como/oq/qndo/pq (não necessariamente todos, mas pelo menos 1 creio eu) para outra pessoa que quiser implementar novas funções, ou rever a estrutura.

      Eu comento muito meu código e na minha opinião eu tenho um código legivel. Acho que voce não deve ter muita experiencia em empresa, pois existe trechos que são modificados quase que diariamente, onde eu apenas acho possível isso descrevendo como o mesmo funciona.

    • Jonas Torres disse:

      Descordo!

      Há casos que é interessante o comentário da regra de negócio utilizada para a resolução do problema.

      Há casos em que você está utilizando recursos avançados da linguagem que uma minoria conhece. Neste caso é bom colocar uma referencia para um ou dois links que você achou na internet para facilitar o trabalho de outra pessoa.

    • Fernando Machado disse:

      Como diria o Fowler…
      “Qualquer tolo consegue escrever código que um computador entenda. Bons programadores escrevem código que humanos possam entender.” (Martin Fowler)

      Ou ainda…
      “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.” (autor desconhecido)

    • Fábio Martinazzo disse:

      Não tão simples assim.. pelo menos não na maioria dos projetos…

      Escrevi isso láaa em cima…

  • Vagner disse:

    // Dear maintainer:
    //
    // Once you are done trying to ‘optimize’ this routine,
    // and have realized what a terrible mistake that was,
    // please increment the following counter as a warning
    // to the next guy:
    //
    // total_hours_wasted_here = 16

  • ProgramadorREAL disse:

    Na verdade, acho que a principal função dos comentários é se divertir… (Mandar recados, reclamar da vida, filosofar…)

  • Victor Hugo disse:

    CRUD não precisa de comentários (se for bem escrito). Comentário não é para substituir nada, é para deixar clara a funcionalidade de um bloco de código. Porém, nem todo o código é tão simples.

    Qual o número mágico para a quantidade de linhas?

  • Albaney Baylão disse:

    Lendo os comentários percebo que existem dois extremos inválidos por aqui: aqueles que acham que comentário é essencial, e aqueles que acham que comentário é dispensável. Se você comenta para explicar **O QUE** o seu código faz, então ou o seu código é muito mal escrito ou o seu comentário foi dispensável. Agora **POR QUE** você fez daquela maneira e não de outra? Quais são as premissas que aquele seu código tem? O que você espera que seja verdade quando aquele código estiver sendo executado? Isto é essencial ser documentado!

  • Felipe disse:

    Eu já vi piores, tipo:

    //Refresqueia o check
    checkbox1.refresh();

  • Mestre Silfer disse:

    Comentário para ajudar a entender a lógica é sempre útil.
    Principalmente em procedures SQL.
    Outro detalhe é evitar a perda de tempo de ler o código inteiro cada vez que você vai dar manutenção ou precisa parar no meio. Imagina ter que reler todo código já pronto, porque precisou parar a codificação no meio?
    Acho comentários sempre válidos.
    Mas iguais aos do Alonso… totalmente dispensáveis

    • Aramati_ disse:

      Pois é, o pessoal que diz que codigo bem feito dispensa comentarios deve estar pensando em casos assim:
      // função para calcular salario
      public calculaSalario( double salarioBase, double descontos, double bonus){

    • Rafael disse:

      A partir do momento que um sistema precisa utilizar procedures SQL que contenha regras de negócio, ele mesmo já está todo errado!!! Procs jamais!!!

      • Bitetti disse:

        Uma store procedure vc usa para manipular os dados de forma mais complexa, não necessáriamente as regras de negócio mas atualizar um campo com suas meta-tabelas já é caso legítimo para uma procedure.

        Se vc visse a faculdade aqui do lado … resolveram ensinar aos alunos que se podia fazer um sistema unicamente com o banco e suas procedures! Ai sim eu concordo que tinha q matar!

  • os comentários podem poupar tempo, explicando o que aquela função vai fazer, sem que você tenha que interpretá-la mentalmente. Isso economiza tempo na manutenção. Gosto de colocar pequenos comentários mesmo que o código esteja bem escrito, para facilitar o trabalho.

    Outras pessoas, mesmo que tenham seu nível de conhecimento, precisam entender a lógica usada no código.

    Chefe gosta de muitos comentários nos códigos. Assim, se um dia ele contratar algum Alonso da vida, fica mais fácil ele entender como as coisas funcionam (sem que ele fique o dia todo no seu pé).

    No meu trabalho já encontrei comentários do tipo
    # powered by Chico Xavier

  • Davi disse:

    Documentação ta ai pra ajudar =D

  • Felipe Barth disse:

    Já vi uns assim

    /* Aqui começa a mágica */

    /* Aqui começa o efeito cascata boa sorte */

    /* Para saber como funciona essa função pergunte para o Mauro */ Obs: Nunca trabalhou um Mauro aqui.

  • Rodrigo VM disse:

    Comentário na minha opnião leva ao erro.

    Uma situação muito comum é o programador colocar um comentário do tipo:

    /*** calculo de financiamento ****/
    /*** Formula: (valor / parcelas * taxa) + (periodo * taxa ….) */

    Bem, depois de um tempo, mudam a formula do financiamento, mas não mudam o comentário…

    Depois de uns anos, algum gerente quer entender como é feito este cálculo por algum motivo, outro programador vem e só lê o comentário e passa a formula errada.

    Comentarios de mudanças, correção de bugs, quem realizou e etc… São interessantes no repositório.

  • JEloy Al Majid disse:

    /*
    Comentei as linhas abaixo, porque essa m… está toda bugada. O FDP que escreveu
    esse código não tem um pêlo no c*. De tanta m… que fez que não foi homem de pôr uma
    única linha de comentário assinando a obra.

    E se achar ruim essa p… de comentário venha falar comigo.

    Firegun
    07/JUN/2010
    */

  • Xtian Xultz disse:

    Eu não escrevo comentários, eu escrevo romances, eu tenho mais comentários que códigos. Mas eu faço isso prá me proteger de mim mesmo, basta algumas horas e eu não faço mais a menor ideia do que o código que acabei de escrever faz. Eu sei, eu sou um mané, mas que que eu posso fazer…

    • Rafael disse:

      concordo, com a correria que se passa no dia a dia fica dificil relembrar toda a lógica do que o processo que voce esta dando manutenção tem que fazer, ainda mais multiplicando a quantidade de clientes e sistemas que cada um pode possuir.

    • @wbarbosa_ disse:

      Regra que uso: 1 linha de comentário a cada 5 a 10 de código (Linhas em branco não contam!)

  • anderson disse:

    function faznada(){
    /*
    script bundao faz nada
    */
    }

    /* pog para IE by FULANO */

    /* melhorar este código depois */

  • renan disse:

    //abre a tela inicial
    abreTela(“inicial”);

  • @derlandyb disse:

    Já teve do tipo:

    /* Se chegar aqui fu*** */

  • @ProgramadoraBR disse:

    Eu faço cada comentário idiota. Em uma equipe com muitos programadores às vezes a gente faz uma coisa e vem um sem avisar e mexe. Da muita raiva… Então eu comento assim: //Feito por Claudia. Antes de mexer me avise.

  • Virgilio Ximenes disse:

    Javadoc taí pra isso!!

  • @derlandyb disse:

    Pior mesmo é quando o comentário diz uma coisa, o nome da função nem de longe remete ao comentário e o que o código faz não é nem uma coisa nem outra.

  • Márcio Almada disse:

    Precisava mesmo de tantos comentários pra dizer que comentários ñ tem importância?

  • Já peguei umas coisas grotescas igual a essa:

    /*
    1 , 2 , 3 já contei agora é sua vez e conte em japones…
    */

    ou então:
    /*
    As tranças de Rapunzel…
    */

    O que você espera de um código desse? rs

  • Celso disse:

    Ja vi um comentario assim:

    …e resolve todo o problema…FANTÁSTICO NAO ACHAM!!!

    eu juro que chamei uns colegas pra ver q por sinal nao foram nenhum
    q escreveu aquilo né? tb quem vai assumir com o chefe ao lado kkkkkk

  • Heitor Silva disse:

    E quem já viu
    /* função papel higienico */
    ?

  • Andre Luiz disse:

    Nossa! Nunca imaginei que minha sugestão de tirinha seria tão comentada em tão pouco tempo (risos)!

    Acho que o principal problema de comentários é que o pessoal escreve o que não precisa e não escreve o que precisa. Por exemplo, nunca acho arquivo-fonte com um comentário no início explicando a arquitetura do programa, a interação entre as threads, etc., mas sempre acho coisas do tipo:

    // Alocando o buffer
    byte[] Buffer = new byte[BufferSize];

    // Incrementando o contador
    Counter++;

  • Bruno disse:

    Isso aqui é tudo obra de uma mesma pessoa:

    // Faz as coisas que tem que fazer

    //NumAnterior : String; // Tem por objetivo eliminar um efeito colateral que
    // ainda não consegui eliminar.

    // Em comentario para ver se funciona…

    GetNumero + // Tomei emprestado. Nao precisa devolver, hehe

    { Incluido para o cliente XXXXX. E seja o que Deus quiser…}

    Isso é só parte dos comentários, o código é bem pior!

  • Não é interessante que a tirinha sobre comentários esteja para bater o record de comentários?

  • rgrlinux disse:

    Acho que para tudo existe o bom senso, gosto muito do livro Código Limpo, e sempre sigo suas teorias, comentários somente onde é extritamente necessário, funções e váriaveis com nomes claros indicando para que e o que fazem, comentáros redundantes só atrapalham, assim como numeros mágicos e variaveis com nomes extranhos, alguns ai comentaram que algumas funções eram curtas, esta é uma das sinteses do livro, se um função ou precedimento tem muitas linhas é por que ela esta fazendo mais de uma coisa e cada funcao ou procedimendo deve fazer bem uma coisa somente. a e também não adianta comentar e não atualizar, atrapalha mais ainda.

  • Waldney Andrade disse:

    “Agora vou escrever: Irmãos e irmãs, vamos brincar de aprender a ler, e parar de ficar discutindo #$%#!#. ”

    Irmãos e irmãs, vamos brincar de aprender a ler, e parar de ficar discutindo #$%#!#.

  • Darkmatter disse:

    Opa já entrou no box de tópicos mais comentados hehe

  • Werner disse:

    Uahahahahah, adorei a camiseta!!
    :-D

  • Dudu disse:

    Na verdade “código limpo” costuma ter pouco ou nenhum comentário…
    Se precisa realmente de comentários, pode ser um “bad smell”…
    :)

  • Bitetti disse:

    Tenho manias de colar links de fontes de referência nos comentários.
    Esses dias errei de aba no navegador e colei um link do Sedentario tipo “Segunda rima com bunda”
    Por algum motivo naquela tarde o rendimento do pessoal caiu para zero.

  • Marcos A. Lucas disse:

    Comentário preferido por um amigo meu, toda vez que ele editava algum código mais “complexo”:

    /* WELCOME TO THE JUNGLE! */

  • kAlug disse:

    Mais alguns exemplos de comentários: StackOverflow (pena que tiraram de lá)

  • Albaney Baylão disse:

    Alguns comentários: ;^)

    1) Se você precisa de um comentário pra dizer o que uma função/método faz, você escolheu mal o nome dela.
    2) Se você precisa de um comentário pra dizer o que uma variável armazena, você escolheu mal o nome dela.
    3) Se você bater o olho no código de uma função/método faz, ou você não sabe direito a linguagem ou ela faz algo que deveria ser quebrado em duas ou mais funções.
    4) Se alguém que sabe a linguagem demora mais do que 5 segundos para entender o que uma função/método faz, o autor deveria ter quebrado ela em duas ou mais.
    5) Comentários devem conter principalmente informações que não estão presentes no código. De preferência apenas informações que não estão presentes no código.

    • Marcelo Fuchs disse:

      Concordo Plenamente!

    • Troller disse:

      Quando você programa então não usa documentação, estilo Javadoc ? Você sabe, só de ver o nome, o que o método espera e o que ele vai retornar ? Você nunca acessa a internet pra procurar a documentação de algum método de algum biblioteca, porque afinal, tudo é “tão óbvio” ?

      Você está realmente num nível muito acima dos outros mortais.

      • Albaney Baylão disse:

        Troller,

        a) Se você faz um comentário por que uma ferramenta geradora de documentação pegará este comentário e gerará a documentação então este comentário não se encaixa em nenhuma das categorias acima.

        b) Se você procura na internet o que faz um método ou função é por que você não está vendo o código dela e portanto você não está se encaixando em nenhuma das categorias acima.

        c) Eu nem sempre sei só de olhar o nome de um método/função o que ele faz. Quando isto acontece é por que o nome foi mal escolhido. Mas o critério não sou eu. Se qualquer um que saiba o básico de programação olha o nome e não sabe o que a função faz, então o nome foi mal escolhido.

        Houve um tempo em que os nomes das variáveis e funções eram curtos para economizar espaço em memória, ou para economizar digitação. Hoje com memória farta e IDEs que autocompletam a digitação não há por que usar nomes descritivos para as funções e métodos.

        O seu código deve ser o mais auto-explicativo possível, com nomes de variáveis/atributos e de funções/métodos claros e que dispensem comentários.

        Agora, as boas razões para se usar comentários:

        A) Geração automática de documentação.
        B) Explicar as premissas embutidas no seu código. Por exemplo, você pode dizer que a função/método por razões de desempenho espera que os valores passados sejam sempre válidos e portanto não testará os parâmetros por valores inválidos. Se a premissa neste exemplo é válida ou não é outra discussão.
        C) Explicar as razão de por que o código foi escrito daquela maneira e não de outra.
        D) Lembretes para o futuro. Exemplo /* escrevi este código de forma porca e com pressa, melhorar quando possível */ ou /* alterar este método quando o sistema trabalhar com múltiplos bancos de dados */

  • /temp/ disse:

    /* Escrevi a query, consultei no banco, fiz um fetch_array e um while */…

    True Story

  • Marcelo Fuchs disse:

    Eu já ví :

    /**
    * Encontra baltazar
    */
    Public changeBaltazar() {

    }

    ou
    /*
    * Função que salva o aluno.
    /*
    Public salvarAluno (Aluno aluno) {

    }

  • Com certeza esses comentários estão muito bons! Gostei das aulas!

  • Gabriel Queiroz disse:

    Pergunta de noob: o que quer dizer a palavra “trin” na camiseta?

  • Erick-Master disse:

    Eu já comentei uma vez em um script recente:

    //---------------------------------------------------------
    // Oh shit, nothing accounts VIP?
    //---------------------------------------------------------

  • Pecinato disse:

    Infelizmente concordo com muitos que ja comentaram e falaram que pegar os codigos dessa forma se torna normal.

    Cada codigo que pegamos que da ate tristeza, nao possui documentação e os codigos estao com comentarios errados ou nem se quer possuem comentarios.
    Isso leva noites acordado para resolver e descobrir totalmente o sistema.

    Mais uma tirinha da vida de programador.

  • Ahhh não isso não dah… muit doido.

  • Kepler disse:


    // No time to change this for the moment
    //
    // ( )
    // ( ) (
    // ) _ )
    // ( \_
    // _(_\ \)__ Merde!
    // (____\___))
    //

    #define please_do_not_vomit
    #include "sys.ho"
    #undef please_do_not_vomit

  • pogueiro disse:

    /**
    * @param activeEntity Atribui a propriedade ‘activeEntity’
    */
    public void setActiveEntity(Serializable activeEntity)
    {
    this.activeEntity = activeEntity;
    }

  • luciano disse:

    Apesar do apelido, este comentario não é meu não.

    Avalie

  • João disse:

    Legal mesmo foi um comentário em C++ que eu vi que estava assim:
    #define TRUE FALSE //Divirtam-se debugando otários!!

    Mas mais legal ainda foi:
    #define NULL (::rand() % 2) // trollface

  • Vinicius disse:

    Bem, na empresa que trabalho, sou único programador na equipe (único formado da faculdade de programação). A equipe inteira programa os básicos e entende os scripts sem precisar de comentários! Isso é muito bacana! Aprendi lendo códigos deles em como deixar códigos mais fáceis até para iniciantes.

  • Fex disse:

    Pra ter um código bem comentado tem que chamar o Arnaldo Cesar Coelho.

Deixe uma resposta

O seu endereço de email não será publicado Campos obrigatórios são marcados *

Você pode usar estas tags e atributos de HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>