Eu fiz uma pesquisa, mas não encontrei o que estava procurando. Sinta-se à vontade para me vincular se esta pergunta já tiver sido feita.

No início deste mês, este post foi feito:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

Basicamente, para resumir, você é um péssimo programador se não escrever comentários. Minha opinião pessoal é que o código deve ser descritivo e não exigir comentários, a menos que o código não possa ser auto-descritivo.

No exemplo dado

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

O autor disse que este código deve receber um comentário, minha opinião pessoal é que o código deve ser uma chamada de função que é descritiva:

$extension = GetFileExtension($image_filename);

No entanto, nos comentários, alguém realmente fez exatamente essa sugestão:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

O autor respondeu dizendo que o comentarista era "uma dessas pessoas", ou seja, um péssimo programador.

Quais são as opiniões de todos os outros sobre Código auto-descritivo e Código de comentários?

Eu prefiro escrever código de auto-documentação. Um guia para isso é o Código Limpo .

Obviamente, isso não significa que nunca se deve usar comentários - eles têm seu papel, mas IMHO você deve usá-los com cuidado. Essa resposta anterior sobre SO explica meus pensamentos sobre o tópico com mais detalhes.

É claro que, como observou @Niphra, sempre vale a pena verificar se o que eu acredito ser limpo é realmente compreensível para os outros. No entanto, isso também é uma questão de prática. De volta à universidade, escrevi trechos de código enigmáticos simplesmente devido ao uso de nomes estranhos e engraçados para todas as entidades de código, de acordo com meu capricho. Até meu professor desistir de uma de minhas tarefas, observando educadamente que ele não conseguia descobrir qual módulo era o principal :-) Essa foi uma boa lição, então me esforcei para me concentrar em escrever código cada vez mais legível desde então. Atualmente, dificilmente recebo reclamações de colegas de equipe.

Você não deve documentar o que o código está fazendo, mas deve documentar por que ele está fazendo.

Nenhuma quantidade de truques de nomenclatura irá expor os porquês e os motivos, portanto, você deve adicionar comentários para explicar a finalidade dos vários bits de código.

Todos os outros comentários podem ser eliminados com segurança.

Na verdade, não acredito em código auto-descritivo. Há um código mais legível e um código menos legível , dependendo do idioma, do seu conhecimento (como autor original), do conhecimento do sujeito que o lê e da função do código. Mas não, ainda ... deve ser descrito com um breve comentário.

O que está claro para mim agora, que estou nessa área de pensamento , provavelmente não ficará claro para mim daqui a um ano, quando estiver pensando em algo completamente diferente e precisar usar essa parte do código novamente.

Então, comente seu código. Nem todas as linhas (céus, não), é claro, mas coloque algumas linhas de comentário acima de uma função / sub-rotina / módulo , ou de uma parte particularmente complicada, e diga resumidamente o que ela faz. Você vai agradecer a si mesmo em um ano ou dois.

Felizmente, os dois campos desta discussão estão representados aqui, e argumentos a favor e contra para ambos foram mencionados.

Acredito que ambos os campos têm argumentos sobrepostos e, na verdade, concordam com a maioria deles, apenas a maneira de alcançá-los é um pouco diferente.

Argumentos sobrepostos

• O código deve ser legível.
• Os comentários não devem dizer exatamente a mesma coisa que o código, mas fornecer informações adicionais sempre que necessário.
• Todos os nomes de variáveis ​​/ funções devem ter um bom pensamento, para que eles tenham uma boa representação do que são / fazem.
• Código duplicado deve ser evitado.

Agora, a principal diferença é quanto peso é colocado em alguns desses argumentos.

Código autoexplicativo

• Os comentários podem ficar obsoletos, portanto, minimize-os, pois comentários errados são piores do que nenhum comentário.
• Comentários são uma duplicação do código. Tudo o que pode ser escrito em código, deve ser escrito em código.

Mais comentários

• Os comentários são mais legíveis que o código. Inglês simples é melhor para descrever algo.

• Código simples geralmente causa ambiguidade que precisa ser comentada de qualquer maneira. Tentar descrever isso no código, resulta em nomes muito longos. Além disso, você é constantemente confrontado com essas informações 'extras', das quais você só precisa na primeira vez que as encontrar.

Acredito que ambos os campos têm argumentos muito válidos, mas você não deve seguir freneticamente um campo, apenas porque resolve um problema.

Para demonstrar, no livro Código Limpo , o código é dividido em vários métodos menores, chamados apenas uma vez. Os métodos são criados pelo único motivo para documentar o código (e TDD mais fácil). Isso resulta na função inferno . O código é menos legível do que era originalmente e, enquanto refatorava, não se pensava em encapsular o código reutilizável.

Por outro lado, você costuma ver as APIs onde todas as funções são comentadas, apenas porque 'os comentários são bons'. As coisas que deveriam ter sido comentadas ainda não são.

"Sinto muito, mas você é esse cara."

Gostaria de saber por que ele não gosta de comentar: P

Sério, a codificação é arte demais demais para se poder fazer uma afirmação tão abrangente. Às vezes você precisa de comentários, às vezes mais e melhores funções nomeadas. Geralmente ambos.

Procure programação alfabética como um estilo extremo.

A resposta curta, melhor e correta

A idéia de que "código auto-documentado" bem escrito é tudo o que você precisa é um anti-padrão e deve morrer, mesmo quando abre exceções para comentários que explicam "por que". É um mito que você sempre possa escrever todo o código para qualquer algoritmo suficientemente claro para qualquer programador olhar e obtê-lo (ou que não exigirá refatoração ou tempo organizacional que você não possui). Ainda mais importante, mais frequentemente do que não, programadores que pensam escrever código claro não o fazem.

Uma resposta muito melhor do que os comentários deve ser usada apenas para explicar "por que" é que os comentários devem:

• explicar "por que" (é claro)
• explique "o quê" em linhas individuais somente quando o código for complexo ou o objetivo não for claro e não puder ser ou não valer a pena simplificar ainda mais
• explique "o quê" para blocos de código para acelerar a compreensão e localizar o que você precisa

A explicação para fazer backup

As pessoas pensam erroneamente que a única razão pela qual as pessoas usam comentários é explicar o que significa uma linha de código. A verdade é que um grande objetivo de comentar o código é torná-lo mais rápidopara dar uma olhada no seu código e encontrar o que você está procurando. Quando volto a codificar mais tarde ou leio o código de outra pessoa, claro, posso ler e entender uma seção de código bem escrito - mas não é mais rápido e fácil ler o comentário na parte superior dizendo o que essa seção de código faz e ignorar completamente se não é o que estou procurando? Por que ficar lá e descobrir o código, mesmo que seja bem escrito, se você pode dar uma olhada em alguns comentários e entender uma função inteira? É por isso que usamos nomes descritivos para funções - ninguém diz que não preciso usar um nome descritivo para minha função, porque alguém pode apenas olhar através do meu código limpo e escrito para ver o que ele faz.

Por exemplo, se estou pesquisando a função de outra pessoa, é mais fácil ir linha a linha através do código para ver o que está fazendo ou dar uma olhada em três comentários bem escritos em toda a função para ver exatamente o que a função está fazendo e onde está fazendo isso?

Outro anti-padrão é o uso excessivo de funções para comentar seu código. Funções bem nomeadas são uma parte importante da documentação do código, mas às vezes os programadores separam 2-3 linhas de código que nunca serão usadas em nenhum outro lugar em uma função para fins de documentação. Por que o uso excessivo de funções é melhor do que o uso excessivo de comentários? Usar funções como essa é o mesmo que abraçar as instruções GOTO - ele cria um código espaguete que pode ser difícil de seguir.

Essencialmente, quando você trabalha em um ambiente corporativo, onde as pessoas compartilham constantemente códigos e nem sempre têm tempo para aperfeiçoar o código, alguns bons comentários podem economizar muito tempo e frustração. E lembre-se, embora você seja um guru capaz de ler o código na velocidade da luz, provavelmente nem todo mundo em seu escritório é.

Bem, você também precisa se lembrar de algo que é óbvio ou "auto-documentado" para você, pode não ser para outra pessoa ... Talvez alguém com menos compreensão de determinadas funções. Então eu comento quase tudo.

Bem, a coisa com código de auto-documentação é que, dentro dessa função, você encontrará:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

o que é auto-explicativo quando você tem o nome da função, pois são apenas duas linhas. Quando as coisas ficam mais complicadas, você precisa agrupar todas as poucas linhas de código em uma função com um nome descritivo ou usar comentários quando necessário .

Eu nunca entendi por que deveria ser uma questão ou questão, em vez de e / e. Sim, faça seu código o máximo possível de auto-documentação e, sim, adicione alguns comentários às partes que, de outra forma, não seriam claras.

Comentários e o código limpo auto-documentado são diferentes. Código é tudo sobre como fazer as coisas. E os comentários devem cobrir a parte do porquê , que não pode ser explicada no código, seja qual for o seu idioma. Além disso, se o seu idioma for muito limitado e você não tiver contratos, especificações estáticas e até declarações, os comentários devem cobrir os problemas de fronteira do seu código.

Nesse caso, é fácil criar uma função descritiva. Mas eu li muitos códigos feitos por bons programadores que acreditavam que eles eram auto-documentados, e o que havia sido claro para eles era realmente confuso para mim.

$ extension = GetFileExtension ($ nome_da_imagem);

Para voltar ao seu exemplo, posso enviar uma matriz de nomes de imagens para ele ou leva apenas uma imagem? Ele suporta algum tipo de arquivo, ou apenas alguns deles? Será que vai garantir a corda para mim, ou eu tenho que fazê-lo? Se o tipo de arquivo não existir, ele me notificará?

Claro, estou esticando um pouco isso. Mas lembro-me de um programador que acreditava que audio_bandwidth e video_bandwidth eram nomes de auto-documentação; o áudio acabou sendo expresso em bytes e o vídeo em kilobytes. Demorou muito tempo para descobrir isso.

Um não exclui o outro. Mesmo que seu código seja comentado automaticamente, há momentos em que você pode precisar de comentários regulares para explicar por que o código comentado faz o que faz.

Não concordo com esse artigo e concordo com você até certo ponto. Se você usar bons nomes de métodos, bons nomes de variáveis ​​e métodos pequenos que fazem uma única coisa, o código deve ser simples de seguir.

Apenas tente não ser inteligente, porque código inteligente é horrível de ler e manter. Palavra-chave: manter !

Minha opinião é que os comentários devem descrever o porquê e não o quê. Lembre-se, nesse mundo hipotético e perfeito, seu código é limpo o suficiente para permitir uma leitura fácil, você não precisa explicar o que está fazendo, mas por que escolheu fazê-lo dessa ou daquela maneira.

Se você estiver usando um sistema de controle de origem, poderá usar a mensagem de confirmação para que todos (e você) saibam o que você fez em um determinado momento e, mais importante, por quê.

Você gostaria de evitar escrever comentários, assim como gostaria de evitar qualquer documentação. Quando se trata da própria linguagem de programação, todos estão operando com o mesmo conjunto de vocabulário e sintaxe (quase).

Quando seu aplicativo é para um domínio específico, pode ser difícil envolver todos para concordar e / ou estabelecer um vocabulário comum. Somos ensinados a evitar abreviações e jargões extensos, mas vou chamá-lo

EBITDA

e não

Capital próprioAntes de jurosTaxasDepreciação e amortização

Se você não conhece um, provavelmente não entende o outro. Se a empresa tiver alguma implementação incomum, um comentário ajudaria o próximo programador que tenha experiência no domínio, mas não essa empresa em particular (o que apenas torna as coisas mais complicadas).

Eu acho que precisamos distinguir entre documentação e expressividade do código.

Ao depurar ou revisar o código, você não está lendo um livro. Na maioria das vezes, você só quer pular de método para método e fazer conexões rápidas em sua mente para obter um entendimento básico do que está acontecendo em tempo de execução. Não é a documentação em torno do código, mas a expressividade das assinaturas de código que importa nesse processo, a capacidade delas de serem significativas o suficiente para que você possa identificá-las imediatamente e adicioná-las à sua própria pilha de chamadas interna. Nesse ponto, nosso cérebro (pelo menos o meu funciona dessa maneira;)) tende a considerar grandes blocos de comentários como um ruído, e não como uma ajuda. Portanto, comentários de uma linha ou, melhor ainda, apenas nomes auto-descritivos de métodos e objetos são suficientes aqui.

Se você quiser "ler o livro" de uma classe ou característica em particular, um lugar muito melhor para isso é nos testes de unidade. Testes de unidade bem projetados são, por natureza, reveladores de intenção e muito mais documentados (ou seja, explicativos, detalhados) do que os blocos de comentários mais espessos, pois contêm 1 / as expectativas sobre exatamente o que esse código deve fazer e 2 / a capacidade de verificar essas expectativas em relação ao código real. Um teste de aprovação é cem vezes mais confiável do que qualquer comentário em termos de documentação, porque prova que o que afirma é verdadeiro.

Alguns códigos simplesmente não são auto-documentados e requerem alguns comentários de um colega humano que entendeu e testou essa peça. O que eu tenho abaixo simplesmente não é suficiente para entender, eu acho.

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

Geralmente, sou a favor de escrever código de auto-documentação, com comentários onde não estão claros, pois acho que a maioria dos códigos não se documenta completamente.

Na universidade, fomos ensinados a reformular praticamente todas as linhas de código em inglês com um comentário (provavelmente apenas para adquirir o hábito de entender o que o código realmente faz, em vez de apenas copiar / colar algo e esperar o melhor).

Pessoalmente, acho que isso atrapalha o seu código, tornando-o menos legível do que se fosse apenas comentários ou apenas código. Sou um codificador de C # e os únicos comentários que faço o tempo todo são os blocos de comentário "barra tripla" que são interpretados de volta à documentação do IntelliSense. Se estou me sentindo especialmente culpado por uma maneira específica de fazer alguma coisa, ou se parece especialmente enigmático, darei uma explicação adicional, mas é isso.

IMO: O código de auto-documentação é aquele em que os nomes de variáveis ​​e métodos recebem nomes significativos e contextuais, para que eles descrevam qual é o seu objetivo.

Se você revisitou seu código várias vezes e ainda não encontrou uma maneira de deixar clara a intenção para alguém que conhece o domínio. Reescreva a função. Afinal, não passa de 10 a 20 linhas. Se for reescrever a função de qualquer maneira, é muito longa e é por isso que é ilegível :) rinse-repeat

e, no caso improvável, ainda não está claro o que o código está fazendo e você se lembrou de pedir ajuda aos seus colegas. Bem, todos nós agradecemos por ajudar a evoluir o Linux, porque é o código do kernel que você está escrevendo, certo? se não enxaguar, repita a partir do topo :)

Simplificando, não escreva seus comentários CODE-OS

Confira Code Complete 2nd edition, pg 128-129.

Os tipos de dados abstratos salvarão você deste dilema. O código de auto-documentação é o caminho a percorrer. Comentários podem ser úteis, mas ter

entidades do mundo real em vez de implementações de baixo nível

você pode evitar o uso de comentários.

Uma coisa sobre comentários é que você os escreve uma vez, mas não os vê quando implementa a função, apenas os vê quando altera a função.

Os comentários são realmente úteis quando são interpretados pelo IDE da maneira que o Delphi 2009+ ou o JavaDoc funciona, mas isso é mais uma linguagem de marcação estruturada; portanto, de certa forma, você está programando sua documentação, o que é muito inteligente.

Acredito no mantra de que o código não se documenta, porque você pode ser o melhor programador do mundo (Ada) e ainda não entende nada do que está acontecendo, mas se você documentar o porquê e em pouco tempo como o seu código está fazendo o que faz, você vai ajudar a si e aos outros no futuro.

Os comentários são obrigatórios. Porque quando você escreve código, está escrevendo para suas necessidades atuais, mas também para as pessoas no futuro que precisam ler seu código, descobrir o que você está fazendo, e por que e como fazer modificações.

Se você se lembrar disso, ao codificar / programar?

Como posso tornar isso mais fácil de entender e modificar para futuros codificadores desse código em que estou trabalhando, então você estará fazendo um bom trabalho. Na falta disso, você está dificultando a modificação do código por outras pessoas, e não imagine que nunca será o caso, isso é raro ...

Na maioria dos meus trabalhos, sempre tive que modificar o código de outras pessoas, e o mais horrivelmente escrito, mal documentado.

Portanto, seu hábito de pensar que o documento de código é ele mesmo não está fazendo a devida diligência.

Como programadores, devemos praticar a autodisciplina que pode parecer totalmente desafiadora para programadores inexperientes, mas deve ter hábitos para evitar todas as experiências horríveis que tivemos com o código de outras pessoas. Ou mesmo olhando para o nosso próprio código meses, anos depois.

Confira http://thedailywtf.com. Eles têm toneladas de histórias engraçadas, mas reais, sobre programadores que simplesmente não fizeram a devida diligência.