Padrão de codificação para maior clareza: comente cada linha de código?

142

Eu trabalhei em lojas que produzem softwares críticos para a vida e lidei com as regras de comentários destinadas a manter o código legível e potencialmente salvar vidas. Na minha experiência, embora o requisito se torne uma tarefa de morte encefálica a ser excluída de uma lista de verificação e não me ajude a manter o foco em escrever código compreensível. Isso também distrai meu revisor de pares de ter uma conversa mais significativa comigo sobre como tornar o código mais fácil de entender.

Também classifiquei o código do aluno que não tinha comentários e vi por que eles deveriam ser marcados por negligenciá-los.

Entendo que usar bons nomes, manter estruturas simples, funções curtas e módulos focados manterá o código compreensível o suficiente para que os comentários possam ser minimizados.

Também entendo que os comentários devem explicar por que o código faz o que faz, não como.

Dado tudo isso, é possível escrever bons padrões de codificação que capturam essa idéia? Outros que serão relevantes em uma revisão por pares, mas não se tornarão uma atividade irracional da lista de verificação que produzirá anotações não mais úteis do que: "Você esqueceu de comentar na linha 42".

Um exemplo do tipo de código que esta regra pode exigir quando tratada como uma linha em uma lista de verificação:

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

Se for possível expressar isso corretamente em um documento de padrões, e talvez não seja, gostaria de capturar uma ideia nesse sentido:

Considere um comentário para cada linha, sequência, instrução, seção, estrutura, função, método, classe, pacote, componente, ... de código. Em seguida, considere renomear e simplificar para eliminar qualquer necessidade desse comentário para que você possa excluí-lo. Faça o check-in enquanto os comentários são raros. Repita até o prazo final. Então repita um pouco mais

candied_orange
fonte
21
Comentários não são para discussão prolongada; esta conversa foi movida para o bate-papo .
maple_shaft
32
"Os comentários não são para discussão prolongada", mais verdadeiro para os comentários do código. :) Esses /* Display an error message */comentários são horríveis e realmente afetam a legibilidade.
Andrea Lazzarotto
Precisamos que nossos IDEs tenham opções para ocultar comentários. Talvez uma opção para comentários em bloco e em linha oculta separadamente. Dessa forma, você tem o melhor das duas opções. Coloque muitos comentários, mas tenha a opção de ocultá-los para manter o código limpo e organizado.
Doug.McFarlane
1
@ Doug.McFarlane Eu pensei que deveria existir para vim. É claro que funciona nos níveis de arquivo e bloco - rtfm-sarl.ch/articles/hide-comments.html !
Michael Durrant
1
Também alternando - stackoverflow.com/a/11842371/631619
Michael Durrant

Respostas:

171

A resposta de Michael Durrant não é ruim, mas ela não está literalmente respondendo à pergunta (como ele próprio admitiu), então tentarei dar uma resposta que:

Também entendo que os comentários devem explicar por que o código faz o que faz, não como.

Dado tudo isso, é possível escrever bons padrões de codificação que capturam essa idéia?

Obviamente, você pode escrever uma lista de verificação para suas revisões de código , contendo perguntas como

  • "se houver um comentário, isso explica por que o código faz o que faz?"
  • "cada linha do código - em seu contexto - é auto-explicativa o suficiente para que não precise de um comentário ou, se não, é acompanhada de um comentário que preenche essa lacuna? Ou (preferencialmente) o código pode ser alterado para não precisa mais comentar? "

Se desejar, você pode chamar isso de "padrão de codificação" (ou não, se você acha que o termo padrão de codificação deve ser reservado para uma lista de regras de braindead, fácil de responder se elas forem cumpridas ou não, como a formatação do código deve parecer ou onde declarar variáveis). Ninguém o impede de focar sua lista de verificação em questões semânticas , em vez de seguir o caminho mais fácil e colocar apenas regras formais nele.

No final do dia, você deve ter certeza de que sua equipe precisa dessa lista de verificação. Para aplicar essas perguntas, você precisa de programadores com alguma experiência como revisores e precisa descobrir se realmente melhorará a legibilidade do código em uma equipe de especialistas. Mas isso é algo que você deve resolver junto com sua equipe.

Doc Brown
fonte
45
Quem votou negativamente nisso? Essa é a resposta para o desenvolvimento crítico de software. Este é um mundo diferente comparado ao local onde a maioria dos programadores trabalha. Nesses mundos, um padrão de codificação que exige que cada linha de código tenha seu próprio comentário não é a resposta certa. Nem é deixar comentários. OTOH, sujeitar os comentários à revisão de código é exatamente o tipo certo de padrão para software crítico. Torna o código mais passível de revisão e manutenção, mas isso tem um custo. Esse custo é pouco comparado aos processos multimilionários resultantes de softwares mal escritos.
David Hammen
4
resposta sábia. se pudéssemos encontrar regras genuínas para codificação, não precisaríamos de programadores. nós poderíamos apenas ter o código das máquinas. poderia acontecer! :(
4
@ DavidHammen: obrigado pelo seu comentário. Na verdade, acho que isso não se aplica apenas ao "desenvolvimento crítico de software". Todo software que é mantido e evoluído ao longo dos anos, geralmente por pessoas diferentes, se beneficiará de ser compreensível para o próximo programador de manutenção.
Doc Brown
5
Este é um bom conselho para qualquer codificação, não apenas o código mantido por pessoas diferentes. Mesmo se você for o único a usar um script / programa, o futuro que precisar modificar o código em um ano apreciará a clareza (e o tempo economizado por não ter que decifrar o código opaco).
Anthony Geoghegan
5
Você poderia editar a "resposta mais votada atualmente" para algo mais objetivo? Nem todo leitor conhecerá o histórico de votação dessas respostas.
candied_orange
151

Grande antipadrão, levando a código de baixa qualidade com menos clareza

btw leitores, o título era originalmente "comentar cada linha de código?" e você pode imaginar a reação instintiva de muitos de nós, inclusive eu. Mais tarde, retomei o título para o título mais longo e preciso.

No começo, lendo sua pergunta, pensei, você duplicou o material nos comentários, mas tudo bem, talvez se você tiver restrições suficientes nas críticas de várias pessoas ... mas, novamente: as pessoas cometem erros, deixam de notar inconsistências etc. e ao longo do tempo acabará havendo diferenças. Pensando bem, acho que o problema é muito maior:

Os desenvolvedores tendem a escrever código pior. Eles usarão nomes e estruturas mais enigmáticas porque 'está explicado no comentário - veja!'.

Considerar:

living_room_set = tables + chairs.

Agora considere:

set = tbls+chrs # Make the set equal to the table plus the chairs

Você não apenas tem mais nomes enigmáticos e mais para ler, mas também precisa olhar para frente e para trás, ver código, o que é um conjunto? olhe para a esquerda no código, olhe para a direita nos comentários, o que são tbls, olhe para a esquerda no código, olhe para a direita nos comentários, o que são chrs, olhe para a direita no comentário. Yuch!

Sumário

Desenvolva ou aprimore um padrão de comentários se você for forçado a ocupar sua posição atual como desenvolvedor (como uma programação COBOL anterior, com certeza já vi grandes!), Mas gastou tanto tempo quanto energia e paixão discutindo contra os comentários anti- padrão usando os argumentos:

  • Código e Comentários ficam fora de sincronia quando apenas um é alterado

  • Comentários podem descrever o que uma pessoa pensa, mas pode estar errado e, assim, encobrir bugs

  • Código fica mais difícil de ler

  • Bom código fica mais difícil de escrever

  • Tendência a usar nomes mais enigmáticos

  • Caracteres excessivos para ler em código e comentários

  • Editores diferentes usam estilos diferentes

  • Requer maior proficiência na língua inglesa do que apenas codificação

  • Leva tempo, recursos e subtrai do valor de longo prazo *

Além disso, defenda um código melhor sem esses comentários, - de fato, tenha um padrão (!) - todos os nomes de variáveis ​​devem ser full_english_words - existe um! Portanto, use a energia desses 'padrões' para os padrões de código e testes bem escritos.

Um dos dois problemas difíceis é nomear coisas - não pule o problema com comentários.

Dado que um dos outros problemas é a otimização prematura e que a otimização em geral pode levar a obscurecer o código 'por que esse caminho', essa é uma área em que comentários explicativos para código aparentemente ruim podem ser benéficos, embora as advertências acima ainda se apliquem.

* código de amanhã

Michael Durrant
fonte
8
Eu não acredito que você respondeu à pergunta. A questão não é ter comentários em todas as linhas. Ele está perguntando como dizer aos desenvolvedores para comentar o código sem fazer com que eles comentem todas as linhas.
hichris123
7
Sim, eu não estou respondendo à pergunta sobre padrões específicos, mas tentando ajudar as pessoas a não seguir esse caminho. Portanto, essa pode não ser a resposta para uma pergunta específica, mas contém conselhos valiosos que são difíceis de definir em um comentário.
quer
1
Qual é o outro problema difícil?
David Grinberg 21/11
20
Invalidação do cache do @DavidGrinberg e erros pontuais .
Eric Rei
1
Cada um dos motivos para evitar comentários pode ser combatido, mas o StackExchange não permite comentários suficientes (heh) para que eu os resolva aqui. Simplesmente: comentar demais é como fraude eleitoral: acontece, mas muito raramente; Quando foi a última vez que você realmente viu isso acontecer? Escrever bons comentários não deve ser simplesmente uma reflexão tardia; se feito corretamente, ajuda no processo de desenvolvimento. Sim, são necessários recursos, mas a recompensa é um código melhor. Você nunca será capaz de obter o mesmo retorno, sacrificando comentários para obter um melhor padrão de nomeação de variáveis. Sim, comentar cada linha é uma loucura.
kmoser
23

Não acho que um documento de padrões de codificação seja o local para especificar o que já é bom senso. O objetivo de um padrão de codificação é garantir consistência (e evitar argumentos) sobre questões em que pessoas razoáveis ​​podem discordar e não há uma resposta certa e óbvia, por exemplo, convenções de nomenclatura, recuo etc.

Comentar como no seu exemplo é objetivamente inútil e pode ser devido a um desenvolvedor inexperiente ou a um desenvolvedor que costumava trabalhar com um sistema de construção que verifica mecanicamente a presença de comentários (uma péssima idéia, mas existe). Nos dois casos, a solução é a educação, possivelmente por meio de revisões de código.

Se você começar a adicionar todos os tipos de "práticas recomendadas" ao padrão de codificação, acabará repetindo o que já está indicado em vários livros. Apenas compre "Código Limpo", "Código Completo" e "O Programador Pragmático" para o desenvolvedor em questão e mantenha seu padrão de codificação baixo.

JacquesB
fonte
63
Uma das muitas coisas que aprendi depois de mais de 40 anos nessa raquete é que o bom senso não é nada comum.
precisa
10
Não existe senso comum.
Whatsisname
1
in_programming não .. mundo real oh sim, mas é apenas um termo para mundo real expereienced conhecimento
Michael Durrant
@ JohnR.Strohm: Minha experiência foi muito mais positiva que a sua, mas também vi como o uso do bom senso pode ser desencorajado ativamente pela imposição de regras mecanicamente.
JacquesB
Estou de acordo com 99,9% desta resposta. O Padrão de Codificação deve ser o que os desenvolvedores apontam quando ocorre um debate na Code Review. A revisão de código visa enriquecer o produto e não iniciar guerras. Tantas guerras que eu vi instigadas pelas Revisões de Código sem o Padrão de Codificação. Ouso dizer que, se você não pode automatizar a verificação dos itens no padrão de codificação, ele deve estar lá. Uma revisão de código é o momento de transmitir 'senso comum' a outros desenvolvedores menos experientes. Não é hora de brigar pela nomeação de variáveis. linux / kernel / gen_init_cpio.c linha 335.
Andrew T Finnell
19

Não é possível. O que você está essencialmente tentando fazer é quase mecanizar o bom senso.

Ao escrever software crítico, como para sistemas médicos de suporte vital, enormes quantidades de listas de verificação e outros enfeites são praticamente inevitáveis. Não apenas as pessoas inteligentes cometem erros, como muitos dos softwares para esses dispositivos são criados por pessoas que não são muito boas em seus trabalhos, por isso o 'sistema' precisa ser capaz de se proteger contra o trabalho malfeito, tornando-o seguro em a despesa de comercialização.

Sua melhor opção é deixar de fora o rigoroso padrão de codificação para comentar e liderar a equipe pelo exemplo. Mostre a outros como são os bons comentários, esforçando-se para produzir um código de boa qualidade que seja devidamente comentado. Em vez de tentar encontrar a melhor maneira de descrever como escrever comentários (que são mais frequentemente do que um julgamento), mostre aos outros o que você quer dizer diariamente com suas próprias análises de código. Enquanto os outros membros leem seu código, eles seguirão o exemplo, se acharem útil. E se não puderem, nenhum Padrão os ajudará a escrever melhores comentários para começar.

whatsisname
fonte
1
+1 para "Você está tentando mecanizar o bom senso", -1 para "Sua única opção é apenas esperar o melhor" e isso me deixa sem votar. Educar e treinar sua equipe também é uma opção. Os padrões podem permitir julgamento.
Curinga
1
@Wildcard Talvez você possa explicar como uma Norma pode permitir julgamento? Não seria um guia nesse ponto? Um padrão é "uma ideia ou coisa usada como medida, norma ou modelo em avaliações comparativas". Como alguém pode usar algo inerentemente subjetivo, tão subjetivo que depende de quem o está lendo, como uma medida de qualidade?
Andrew T Finnell
1
@Wildcard: O problema é que, quando você entra em setores regulamentados, o processo é superior a tudo, ter um processo é mais importante do que se o processo vale a pena ou não. Tudo precisa se resumir a caixas de seleção de alguma forma, todas as caixas de seleção precisam ser específicas e verificáveis, e quanto mais você tiver uma caixa de seleção, maior o risco de ser incomodado em uma auditoria.
Whatsisname
É um mundo estranho, e lembre-se de que as regras são escritas por burocratas com pouco conhecimento do domínio do software, e muitas vezes você acaba com sistemas que existem para justificar e exigir a si mesmos, em vez de ser um meio para atingir um fim para garantir produtos de qualidade.
Whatsisname
1
@whatsisname Estou muito feliz por ter alguém que entenda. Suas respostas são escritas de maneira mais elegante e precisa do que eu jamais poderia ter tentado. A afirmação with systems that exist to justify and require themselves rather than being a means to an end to ensure quality productsé EXATAMENTE o que eu estava tentando ilustrar. Obrigado por encontrar minhas palavras para mim. Eu realmente quero dizer isso. Temos que separar a idéia de induzir qualidade da ideia de seguir um processo, pois eles não são os mesmos. É por isso que temos controle de qualidade, Stackoverflow e clientes que perdoam muito.
Andrew T Finnell
14

Atualizar

Minha resposta entre aspas para ênfase:

É minha convicção que a resposta que afirma que os comentários não devem ser abordados nas normas de codificação e, em seguida, lista um conjunto de perguntas defensivas para combatê-la, é a única resposta correta.

A questão aqui é que um padrão de codificação é apenas isso, um padrão . Idéias extremamente subjetivas não devem estar em um padrão de codificação . Pode ser um guia de práticas recomendadas, mas esse guia não pode ser usado contra um desenvolvedor durante a Revisão de Código. Na minha opinião pessoal, um Padrão de Codificação deve estar o mais próximo possível de Automatizado. Há muito tempo desperdiçado nas Revisões de Código, discutindo sobre nomeação, espaçamento, guias, colchetes, comentários etc. etc. quando tudo pode ser automatizado. Até a resposta tablese chairspode ser automatizada. Os LINT permitem dicionários, verificações de maiúsculas por conceito (variável, função, método, classe etc.).

Até a verificação JavaDoc pode ser implementada por um Robot LINT'er antes que uma solicitação de recebimento seja aceita. Muitos projetos de código aberto fazem exatamente isso. Você envia sua solicitação de recebimento, o código é criado com um arquivo Travis-CI, incluindo a Static Analysis, e deve passar por todos os padrões de codificação que podem ser expressos objetivamente. Nenhum carrilhão humano fala sobre "fazê-lo incorretamente" ou não "fornecer valor" com um comentário, ou a maneira errada de nomear variáveis, etc. Essas discussões não têm valor e são melhor deixar para um robô de terceiros que pode suportar o impacto de nossa codificação emocional.

Para realmente responder à pergunta, teríamos que abordar como escrever uma Norma que aborda como responder à seguinte pergunta: Esse comentário forneceu valor? Um padrão de codificação não pode ditar o 'valor' de um comentário. Portanto, torna-se necessário que um humano passe por essa lista de verificação. A simples menção de comentários em um Padrão de codificação cria uma lista de verificação que o Pôster original deseja evitar.

É por isso que os comentários geralmente não são processados ​​pelo compilador e removidos. Seu valor não pode ser determinado. O comentário em questão é valioso; sim ou não?. Responder a esta pergunta é NP-difícil. Somente os humanos têm a chance de responder adequadamente, e mesmo assim, só pode ser respondido no momento em que é lido, pela pessoa que está lendo; onde o valor desse comentário é afetado pelo clima, sua vida familiar, a última reunião em que eles acabaram de participar e não terminaram bem, a hora do dia, a quantidade de café que tomaram. Confio que a imagem está se tornando mais clara.

Como isso pode eventualmente ser expresso adequadamente em qualquer Padrão? Um padrão não é útil, a menos que possa ser aplicado de forma consistente e justa, onde justo é mais sobre objetividade e não emocional.

Concordo que um Padrão de Codificação deve permanecer o mais Objetivo possível. A maneira como as variáveis ​​são chamadas de objetivo IS. Eles podem ser facilmente verificados em um dicionário quanto à ortografia, estrutura gramatical e revestimento. Qualquer coisa além disso é uma "partida irritante" que é vencida pela pessoa com mais poder ou por "surra". Algo que eu, pessoalmente, luto por NÃO fazer.

Quando eu comento, sempre comento conversando com o meu eu futuro na terceira pessoa. Se eu voltar a esse código em cinco anos, o que eu precisaria saber? O que seria útil, o que seria confuso e o que estaria desatualizado com o código? Existe uma diferença entre o código de documentação para gerar uma API pública pesquisável e o código de comentário que agrega valor a terceiros desconhecidos, mesmo que esse terceiro seja você mesmo.

Aqui está um bom teste decisivo. Se você era o único no projeto. Você sabia que seria o único no projeto. O que estaria no seu padrão de codificação? Você deseja que seu código seja limpo, auto-explicativo e compreensível para si mesmo no futuro. Você gostaria de fazer uma revisão de código sobre por que não colocou um comentário em todas as linhas? Você revisaria todos os comentários criados nos 100 arquivos que fez check-in? Se não, então por que forçar os outros?

Algo que acredito estar faltando nessas discussões é que o Future You também é um desenvolvedor deste projeto. Ao perguntar sobre valor, amanhã você também é uma pessoa que pode derivar valor do comentário. Então o tamanho da equipe, na minha opinião, não importa. A experiência da equipe não importa, ela muda com muita frequência.

Nenhuma quantidade de código de comentário revisando isso impede que o marcapasso caia e mate um paciente. Depois de falar sobre um comentário que afeta o código, agora você está falando sobre o código e não o comentário. Se tudo o que é necessário é um comentário que falta para matar alguém, há algo mais que cheira no processo.


A solução para esse tipo de maneira rigorosa de codificação já foi fornecida como uma metodologia para escrever o próprio software. E não tem nada a ver com comentários. O problema dos comentários é que eles NÃO têm impacto na maneira como o produto funciona. Os melhores comentários do mundo não podem impedir o software de travar quando incorporado a um pacemaker. Ou ao medir os sinais elétricos com um eletrocardiograma portátil.

Temos dois tipos de comentários:

Comentários legíveis por máquina

Estilos de comentário como Javadoc, JSDoc, Doxygen etc. são todas as formas de comentar a interface pública que um conjunto de códigos fornece. Essa interface só pode ser usada por outro desenvolvedor (código proprietário de uma equipe de duas pessoas), um número desconhecido de desenvolvedores (por exemplo, JMS) ou por um departamento inteiro. Esse código pode ser lido por um processo automatizado que produz uma maneira diferente de ler esses comentários, como HTML, PDF e outros.

É fácil criar um padrão para esse tipo de comentário. Torna-se um processo objetivo de garantir que todos os métodos, funções e classes publicamente invocáveis ​​contenham os comentários necessários. Cabeçalhos, parâmetros, descrição et. el. Isso é para garantir que seja fácil para outra equipe encontrar e usar o código.

Estou fazendo algo que parece louco, mas não é realmente

Esses comentários estão aqui para ajudar os outros a entender por que esse código foi escrito de uma certa maneira. Talvez haja um erro numérico nos processadores nos quais o código está sendo executado e ele sempre é arredondado para baixo, mas os desenvolvedores geralmente lidam com o código que é arredondado. Portanto, comentamos para garantir que um desenvolvedor que toque no código entenda por que o contexto atual está fazendo algo normalmente pareceria irracional, mas, na realidade, foi escrito dessa maneira de propósito.

Esse tipo de código é o que causa tantos problemas. Normalmente, ele não é comentado e é encontrado mais tarde por um novo desenvolvedor e 'corrigido'. Quebrando assim tudo. Mesmo assim, os comentários existem apenas para explicar o porquê de não impedir que algo realmente se quebre.

Comentários não podem ser invocados

Comentários são em última análise, inútil e não pode ser confiável. Os comentários normalmente não alteram a maneira como os programas são executados. E se o fizerem, seu processo está causando mais problemas do que deveria. Comentários são reflexões posteriores e nunca podem ser outra coisa senão. O código é tudo o que importa, pois é tudo o que é processado pelo computador.

Isso pode parecer estúpido, mas tenha paciência comigo. Qual dessas duas linhas realmente importa?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

Neste exemplo, o que importa é que não temos idéia do que é 'n', não há nenhuma verificação para n ser 0 E, mesmo que houvesse, nada impede que um desenvolvedor coloque n = 0APÓS a verificação para 0. Assim, o comentário é inútil e nada automatizado pode capturar isso. Nenhum padrão pode entender isso. O comentário, embora bonito (para alguns), não tenha relação com o resultado do produto.

Desenvolvimento Orientado a Testes

O que tem um resultado no produto? As indústrias nas quais o código que está sendo escrito pode literalmente salvar ou matar alguém precisam ser rigorosamente verificadas. Isso é feito através de revisões de código, revisões de código, testes, testes, revisões de código, testes de unidade, testes de integração, testes, teste, meses de testes, revisões de código e testes individuais, teste, revisões de código, testes e, talvez, finalmente entrando em produção. Comentários não têm nada a ver com nada disso.

Eu preferiria codificar sem comentários, especificações, testes unitários que verificassem as especificações, estudos dos resultados da execução do código no dispositivo de produção e código bem documentado que nunca havia sido testado, nem tinha nada para comparar o código. código contra.

A documentação é boa quando você está tentando descobrir por que alguém fez algo de uma certa maneira; no entanto, ao longo dos anos, descobri que a documentação é normalmente usada para explicar por que algo 'inteligente' foi feito, quando realmente não precisava. para ser escrito assim.

Conclusão

Se você trabalha em uma empresa que exige que cada linha seja comentada, garanto que pelo menos dois dos engenheiros de software do projeto já escreveram um programa de documentos automáticos em Perl, Lisp ou Python, que determina a idéia geral do que a linha está fazendo , depois adiciona um comentário acima dessa linha. Como isso é possível, significa que os comentários são inúteis. Encontre os engenheiros que escreveram esses scripts para documentar automaticamente o código e usá-los como evidência do motivo pelo qual o 'Comentário sobre cada linha' está perdendo tempo, não fornecendo valor e potencialmente prejudicial.

Por um lado, eu estava ajudando um amigo próximo com uma tarefa de programação. Seu professor havia estabelecido um requisito para que todas as linhas fossem documentadas. Então eu posso ver de onde viria esse processo de pensamento. Apenas pergunte a si mesmo, o que você está tentando fazer, e isso é a coisa certa? Então pergunte a si mesmo; Existe alguma maneira de 'jogar' o sistema com esse processo? Se houver, será que realmente está agregando valor? Não se pode escrever automaticamente testes de unidade, que testam esse código e atendem a uma determinada especificação; se possível, não seria algo ruim.

Se um dispositivo tiver que funcionar sob certas condições, porque estará dentro de um ser humano, a única maneira de garantir que não os matará são anos de testes, revisão por pares, ensaios e NUNCA MAIS NUNCA alterando o código novamente. É por isso que a NASA ainda está usando hardware e software tão antigo. Quando se trata de vida ou morte, você não apenas 'faz uma pequena alteração e faz o check-in'.

Comentários não têm nada a ver com salvar vidas. Comentários são para humanos, eles cometem erros, mesmo quando escrevem comentários. Não confie nos humanos. Portanto, não confie nos comentários. Comentários não são sua solução.

Andrew T Finnell
fonte
3
O problema dos comentários é que eles NÃO têm impacto na maneira como o produto funciona. bem, se a parte humana de leitura e contagem de escrever código eu acho que não afetam o modo como ele em última análise, funciona, mas não como o código executa quando finalmente escrita, sim. Eu diria que o problema com o código é simplesmente que ele fica desatualizado e é pior do que nenhum código!
Michael Durrant
1
Aqui aqui, tínhamos um cronometrista que queria relatórios diários do que fizemos para que ele pudesse otimizar nosso trabalho. De qualquer forma, ficamos um pouco zangados com o fato de precisarmos gastar 15 minutos por dia preenchendo seu formulário, e automatizamos isso preenchendo lixo de nossos registros.
Joojaa
1
Há um problema extra com o comentário "Não dividimos por 0 para interromper falhas". Não está claro gramaticalmente se a cláusula "a fim de" se aplica à ação de divisão ou à sua negação. Se você usar "Evitamos dividir por 0 para ...", evita essa ambiguidade. :)
Curinga
1
"não divida por zero para impedir acidentes", na verdade, me diz muito sobre a mentalidade da pessoa que a escreveu. Você não codifica para evitar falhas! Você codifica para que o código esteja correto e não travar é apenas uma pequena parte da correção. Se o cálculo para a quantidade de medicamento a injectar acaba dividindo por zero, você não retornar algum valor fictício como 99999 ...
immibis
1
@AndrewTFinnell Quero dizer que se você às vezes obtiver uma divisão com erro zero, adicionar "if (divisor == 0) return <something>; // evitar divisão por zero" não tornará seu código mais correto. Em vez disso, você precisa descobrir por que o divisor é zero e corrigir isso. Alguns algoritmos são projetados para que o divisor zero seja inevitável, mas eles são a exceção (e, nesse caso, você pode retornar um valor de "resultado não pode ser calculado").
immibis 23/11/16
12

Você alude a duas coisas diferentes quando fala sobre comentários. Eles não são os mesmos, e a distinção é importante.

A documentação fala sobre os bits externos de um pedaço de código - sua interface.

Normalmente, as ferramentas permitem que você as leia de maneira 'independente', ou seja, você não está vendo o código subjacente ao mesmo tempo.

Toda a interface deve ser documentada (por exemplo, cada método, excluindo métodos privados) e deve descrever entradas, saídas e quaisquer outras expectativas, limitações etc., especialmente coisas que não podem ser expressas por meio de restrições, testes etc. ( Exatamente a quantidade de detalhes e para onde vai depende do projeto).

Uma boa documentação permite que o consumidor em potencial decida se, quando e como usar o código.

Os comentários no código-fonte têm uma finalidade diferente. Eles estão lá para pessoas que olham o código fonte. Eles descrevem principalmente a implementação.

Os comentários são sempre lidos no código subjacente.

Os comentários devem explicar decisões surpreendentes ou algoritmos complexos ou opções não adotadas (e raciocínio). Eles estão lá para que futuros desenvolvedores possam entender os processos de pensamento de seus antecessores e tenham em mãos informações que eles poderiam ignorar ou passar muito tempo procurando, por exemplo

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

Você não pode deduzir nada da ausência de um comentário, e o comentário pode estar tão errado quanto o código ao redor ou mais. O julgamento deve ser exercido tanto por parte do autor quanto por parte do leitor.

Comentar cada linha é claramente mais trabalho de valor adicional questionável, que vem com um custo de oportunidade. Se você tem uma regra que diz que todas as linhas devem ser comentadas, você a receberá, mas às custas de partes importantes serem bem comentadas .

Mas é pior do que isso: o objetivo de um comentário é derrotado se todas as linhas forem comentadas. Os comentários tornam-se ruídos que dificultam a leitura do código: mais obscurecem do que esclarecem. Além disso, comentários indiscriminados dificultam a identificação dos comentários realmente importantes.

Comentários ou documentação não fornecem nenhum tipo de medida ou garantia da qualidade do código que descrevem; eles não substituem o controle de qualidade genuíno. Seu objetivo é prospectivo, ou seja, na esperança de ajudar aqueles que interagem com ele a evitar erros.

Em resumo , seus padrões de codificação podem e devem exigir documentação (as verificações automatizadas ajudam a identificar funções / métodos não documentados, mas os seres humanos ainda precisam verificar se a documentação é boa). Os comentários são um julgamento e seu guia de estilo deve reconhecer isso. Aqueles que nunca comentam e aqueles que comentam sem pensar devem esperar ser desafiados.

user52889
fonte
Documente que a API pública é um bom ponto, mas eu realmente gosto de explicar decisões surpreendentes. É muito bom se as violações do princípio de menor espanto vierem com uma justificativa. +1
candied_orange 21/11
1
+1 para comentários estranhos como ruído. Mantenha o sinal alto ao ruído.
sq33G
Um +1 especialmente para fins de comentário é derrotado se todas as linhas forem comentadas. Pena que isso possa ser (e geralmente é) usado como uma desculpa para não comentar, mas é muito certo de qualquer maneira, pelas razões que você mencionou mais, porque se cada linha for comentada, a maioria das pessoas começará automaticamente e compreensivelmente a ignorar todos os comentários .
SantiBailors
10

Você não pode codificar um padrão de comentários, porque não pode saber qual será o comentário importante com antecedência.

Mas você ainda deseja garantir que o código seja comentado corretamente, pois esse é um código de vida útil. A solução é ter um padrão para a revisão de código - exigir que os comentários de revisão de código sejam compreensíveis.

Isso não garante que não se torne uma lista de verificação sem sentido, mas pelo menos impedirá que o código seja mais difícil de ler. E tem a possibilidade de torná-lo melhor.

Isso requer uma cultura em que uma revisão de código não seja, por si só, um gesto sem sentido, em que receber o código de volta tão difícil de ler é uma coisa boa, e não um insulto ou aborrecimento. Tão importante quanto o que diz que não está claro, não é visto como um fracasso do leitor.

Código ilegível é, até certo ponto, inevitável. Porque o escritor está imerso no contexto e verá algo tão óbvio quando só é óbvio se você souber x, y ou z.

Portanto, você não poderá ter uma regra que dê bons comentários, mas verifique as avaliações. Mesmo um gerente não programador poderia fazê-lo - porque a verdadeira questão não é: o código foi escrito para ser legível, mas era o código realmente legível, que só pode ser decidido por alguém que o leu.

jmoreno
fonte
7
Re Você não pode codificar um padrão de comentários - Claro que pode. Você sujeita os comentários à revisão do código, e esse item que diz que os comentários não explicam o código deve ser endereçado. Essa é uma despesa, uma despesa que a maioria dos ambientes de programação não deseja pagar. Vale a pena em relação a software crítico.
David Hammen
"... quando é óbvio apenas se você conhece x, y ou z" Você pode especificar a quantidade de conhecimento {x, y, z} que precisa ser conhecida com antecedência para ver algo tão óbvio e depois (tipo mecanicamente), você pode verificar se isso é válido para o código atual. Onde não, adicione comentários até que seja.
precisa saber é o seguinte
1
@ DavidHammen: isso não é um padrão para o comentário, é um padrão para a revisão. Foi o que sugeri como solução. Você não pode dizer que deve ter um determinado tamanho ou usar uma sintaxe específica ou até mesmo exigir um comentário útil em primeiro lugar (ou você recebe comentários do tipo "adicione um ao i"). Você pode dizer que o revisor deve comentar o código e os comentários. Como você diz, pode exigir que os problemas levantados pela revisão de código sejam resolvidos. Mas o ônus disso é que o revisor faça um bom trabalho. Somente o revisor pode julgar se o código e o comentário são suficientes.
jmoreno
@DavidHammen As pessoas escolhidas para a revisão fazem o julgamento? E quando eles saem? Se novas pessoas não pensam da mesma maneira ou falam inglês? Se os 'Revisores' saírem? Sua sugestão coloca alguns desenvolvedores no topo de uma torre de marfim, causando dissidência, desconfiança e quebra de comunicação. Os comentários devem fornecer informações ou esclarecimentos para aqueles que podem usá-lo. Talvez Joe precise, mas Mary não. O que acontece quando Mary é a revisora? Ou Joe? Ou Mark?
Andrew T Finnell
@jmoreno - Não colocar regras / diretrizes sobre comentários nos padrões de codificação significa que os programadores precisam procurar várias fontes - e eles não sabem para onde olhar até que a revisão volte dizendo que os comentários são precários. É um erro pensar que tudo em um padrão de codificação deve ser automatizável. Regras sobre nomes significativos, por exemplo, não são automatizáveis. Pelo menos ainda não. Por exemplo, x, y, e z, ou i, je kpodem ser nomes bastante significativas se está a implementar um algoritmo científica baseada em um papel jornal que usou exatamente esses nomes em suas fórmulas.
David Hammen
9

Comentar cada linha de código? Não .

O objetivo das outras regras de que você fala é precisamente evitar isso.

Os comentários para um código legível são, na melhor das hipóteses, redundantes e, na pior das hipóteses, afastam o leitor da busca pelo objetivo inexistente do comentário.

Se você comentar todo o código que é auto-explicativo, duplica a quantidade de leituras sem fornecer nenhuma informação adicional. Não tenho certeza se essa redundância valeria a pena. Pode-se imaginar um revisor dizendo que 42 diz " display_error" enquanto o comentário diz "exibe aviso". Mas imagine uma mudança no código. Você tem dois lugares para corrigir agora. Fica claro que esse estilo tem negativos de copiar e colar.

Eu diria que, idealmente, o código não deve precisar de nenhum comentário, além da documentação.

Existem estilos totalmente opostos, se você tiver dúvidas sobre a linha, é:

  1. O código é muito complicado e deve ser refatorado para uma função com um nome com significado semântico para a parte do código. Seja um complexo ifou uma parte de um algoritmo. (Ou uma linha inteligente LINQ)

  2. Se não puder ser simplificado, você não conhece idiomas suficientes da linguagem.

(Pessoalmente, não sou fanático pela regra estrita de não comentar, mas acho que é uma boa mentalidade inicial.)

Dado tudo isso, é possível escrever bons padrões de codificação que capturam essa idéia?

Quanto ao processo. Nosso padrão deu muito crédito ao revisor. Supondo que eles não sejam maliciosos, isso funciona bem.

Quando ele pergunta "O que é variável o?", Você o renomeia. Se ele perguntar o que esse bloco faz, refatorar ou comentar. Se houve um debate sobre se algo está claro ou não, se o revisor não o entendeu, então, por definição, não está. Em ocasiões muito raras, havia algo como a segunda opinião de alguns amigos.

Em média, você deve obter um código compreensível pelo programador médio da equipe. Na IMO, evita as informações redundantes e garante que o código seja compreensível por pelo menos um outro membro da equipe, o que achamos ótimo.

Além disso, não houve absolutos . Embora fôssemos um pequeno grupo. É fácil encontrar consenso no grupo de 5.

luk32
fonte
2
Usar revisões de código para ditar quais variáveis, classes e métodos devem ser nomeadas é a melhor maneira de fazer as pessoas odiarem uma empresa, negócio ou metodologia. As revisões de código não devem ser usadas como uma maneira de impor coisas que realmente não importam. Um padrão de codificação deve ser verificável por meio de um processo automatizado. Comprimento variável do nome, Complexidade circular, Lei de Demeter, são todas as coisas que podem ser verificadas. Se alguém me dissesse para renomear uma variável de 'i' para algo como indexForThePreviousCollection, eu encontraria outro local para trabalhar. Variáveis> 3 caracteres são todos verificados antes do check-in automaticamente.
Andrew T Finnell
3
@AndrewTFinnell Posso escrever código impossível de seguir em qualquer paradigma de programação que você queira nomear.
candied_orange
2
@AndrewTFinnell Bem, eu discordo educadamente. " Usando revisões de código para ditar ", não sei de onde você tirou isso. Eu não gostaria de trabalhar no código com variáveis i, j, ktodo o lugar depois de o autor original é encerrado. Não entendo seu ponto de vista sobre o genoma "humano". Duvido que exista uma linguagem em que haja uma única afirmação, ou duas sejam muito difíceis de compreender. Como eu disse, eu já vi complexos ife LINQone-liners. Eles podem ser comentados ou refatorados com um nome semanticamente significativo, acho que esse é o seu "bom comentário".
Luk32
3
@ luk32 Eu respeito o direito de discordar. Variáveis ​​de iteração são bastante contextuais óbvias na minha opinião. Embora compreenda o sentimento de sua declaração, acredito que há muitas práticas que levam esse sentimento ao extremo. Nós realmente precisamos de código que leia: for (int indexForCurrentDatabaseRow = 0; indexForCurrentDatabaseRow < currentUserRecordSetResults.length; indexForCurrentDatabaseRow = indexForCurrentDatabaseRow + 1)versus for (int i = 0; i < results.length; i++)? Talvez seja uma questão de preferência e / ou tempo gasto olhando o código. Nomes excessivamente verbosos cheiram para mim.
Andrew T Finnell
2
Não acho que os nomes devam ser decididos nas revisões de código. A revisão de código geralmente deve começar depois que o autor achar que é bom o suficiente, o que também significa que é devidamente comentado, fácil de entender e que as variáveis ​​têm nomes decentes. A questão é: se os revisores acham que o código é muito complicado ou se esforçam com o significado de uma variável, é difícil entender o código. Isso não é discutível - evidentemente pelo menos um desenvolvedor - o revisor - não entendeu. Se é necessário refatorar ou não (e como) ou comentar adequadamente é uma questão diferente.
Idan Arye
9

A questão:

Dado tudo isso, é possível escrever bons padrões de codificação que capturam essa idéia? Os que serão relevantes em uma revisão por pares, mas não se transformarão em uma atividade irracional da lista de verificação que produzirá notas não mais úteis do que: "Você esqueceu de comentar na linha 42".

Os comentários não devem procurar educar o leitor sobre o idioma. Supõe-se que um leitor conheça melhor a língua que o escritor, mas com muito menos contexto que o escritor.

Um leitor deste código, a partir do seu exemplo, deve saber que exit()sairá do aplicativo - tornando o comentário redundante:

/* Exit the application */
exit();

Comentários redundantes são uma violação do DRY e as alterações no código não são propagadas necessariamente para os comentários, deixando comentários que não refletem o que o código está realmente fazendo.

No entanto, comentários que explicam por que você está fazendo algo podem ser valiosos - especialmente se você não pode comunicar facilmente o significado no próprio código.

PEP 8 do Python (o guia de estilo para Python na biblioteca padrão do CPython) fornece as seguintes diretrizes para comentários embutidos:

Use comentários embutidos com moderação.

Um comentário embutido é um comentário na mesma linha que uma declaração. Os comentários embutidos devem ser separados por pelo menos dois espaços da declaração. Eles devem começar com um # e um único espaço.

Os comentários embutidos são desnecessários e, de fato, perturbadores, se afirmam o óbvio. Não faça isso:

x = x + 1                 # Increment x

Mas, às vezes, isso é útil:

x = x + 1                 # Compensate for border

Dado esse exemplo, eu pessoalmente prefiro dar um passo adiante e tentaria eliminar esse comentário também. Por exemplo, posso chegar a:

border_compensation = 1
compensated_x = x + border_compensation

Criando seu código auto-documentado não é uma idéia nova .

De volta à pergunta real:

Dado tudo isso, é possível escrever bons padrões de codificação que capturam essa idéia?

Acredito que a orientação e o exemplo do PEP 8 demonstrem um bom padrão de codificação que captura essa ideia. Então, sim, acredito que é possível.

Aaron Hall
fonte
1
"Supõe-se que um leitor conheça a língua melhor do que o escritor". É difícil acreditar que essa seja a atitude correta. Percebo que eles sabem tanto , mas cada equipe é diferente e cada pessoa em uma equipe é diferente; portanto, uma declaração geral sobre esse ponto em particular não parece sensata.
Bryan Oakley
4
Sem essa orientação, você terá programadores juniores enviando comentários explicando o código trivial para ninguém além de si mesmos, e programadores de nível médio usando soluções estranhas simplesmente para tornar o código mais acessível para programadores juniores. Essa orientação elimina a redundância e garante que mesmo um programador experiente continue aprimorando seu código. Quando revisito o código, posso ter esquecido o contexto, mas, em geral, sei o que a linguagem está fazendo ainda melhor do que quando a escrevi.
Aaron Hall
4

Acho que quando você vê esse tipo de comentário, e eu mesmo escrevo dessa maneira ocasionalmente, é porque o autor está escrevendo a especificação nos comentários e depois passando e implementando cada comentário.

Se somos desafiados a escrever um padrão de codificação que produza um código que seja compreensível em termos de sua funcionalidade requerida, em vez de sua funcionalidade real (para que os erros possam ser detectados), então estamos realmente falando sobre como as especificações são definidas, documentadas e vinculadas a o produto final?

editar ----

Só para esclarecer. Eu não estou entrando em comentários vs tdd vs testes de unidade que melhor. Ou sugerir um comentário por linha é bom / ruim

Estou apenas sugerindo uma razão pela qual você pode ver o estilo de comentar mencionado no exemplo.

E a partir desse questionamento se um padrão de codificação sobre comentários seria realmente melhor escrito como algum requisito de documento de especificação.

ou seja, os comentários são para explicar a finalidade do código, que também é o que uma especificação é

Ewan
fonte
6
Em 20 anos, nunca vi alguém comentar prototipar seu código dessa maneira e preencher as lacunas com o código real. Já existe uma maneira objetiva de alcançar o que você está dizendo ou o que eu acho que está dizendo. Chama-se Desenvolvimento Orientado a Testes. Os testes de unidade definem a especificação e se o código adere a essa especificação. Tudo sem comentários.
Andrew T Finnell
9
Embora eu não ache que o código da pergunta seja um bom exemplo disso, a prática de escrever um procedimento nos comentários primeiro e depois voltar e preencher o código é especificamente chamada em "Code Complete" como um exemplo. prática possível para ajudar a produzir código legível, @AndrewTFinnell. Definitivamente não é algo inédito, mesmo que esteja fora da sua experiência.
precisa
6
Também antecede TDD eu acredito
Ewan
2
Você está falando sobre o processo de programação de pseudocódigo? O objetivo disso era reduzir os comentários. Eu nunca me lembro que o livro com os comentários deve ser deixado no código. E comentar para produzir um procedimento conceitual deve ser de alto nível, e não baixo. Se alguém comentasse todas as linhas que pretendiam escrever, poderia ter acabado de escrever as linhas. A idéia é prototipar os princípios do código e não cada linha. O livro não sugere comentar todas as linhas. Esse é o foco desta questão. E posso estar errado, mas acredito que esteja na Segunda Edição.
Andrew T Finnell
2
@JoshCaswell & Ewan, sim, era uma técnica há muitos anos e realmente antecedeu o TDD. Mas você deveria excluir os comentários depois! E o TDD a substituiu completamente como uma maneira sensata de criar código que atenda a uma especificação.
David Arno
4

Dado tudo isso, é possível escrever bons padrões de codificação que capturam essa idéia? Os que serão relevantes em uma revisão por pares, mas não se transformarão em uma atividade irracional da lista de verificação que produzirá notas não mais úteis do que: "Você esqueceu de comentar na linha 42".

Obviamente, isso vai além da documentação - isso afeta como o código está estruturado, quais algoritmos são escolhidos, etc. Pode até tocar na análise e no design de requisitos.

Minha regra nº 1 é "Não documente o óbvio". A regra nº 2 é "Escreva código óbvio".

Para códigos críticos de segurança (nos quais nunca tive que trabalhar, graças a Deus), esse é um primeiro passo necessário, mas nem de longe o suficiente. Pode até ser necessário determinar quais recursos de linguagem devem ser evitados (eu já vi mais de um padrão exigindo "Você não usará scanf( "%s", input ); por qualquer motivo ").

John Bode
fonte
Óbvio está nos olhos de quem vê. E muda dependendo do prazo.
Tony Ennis
3

A melhor prática de código de autodocumentação não é um consenso convencional - embora seja amplamente aceitável que um código fácil de entender seja melhor que um código criptográfico, nem todos concordam se um código complicado deve ou não ser sempre refatorado ou se é bom comentar isto.

Mas esse debate é sobre partes de código difíceis de entender - e você está falando sobre comentar cada linha de código. As linhas de código difíceis de entender devem ser muito raras - se a maioria das suas linhas for complicada assim, você estará abusando de frases simples e você deve parar! Claro, o papel de uma linha pode às vezes ser um pouco difícil de entender, mas esse é o papel no contexto de um pedaço maior de código - o que a própria linha faz é quase sempre direta.

Portanto, você não deve comentar linhas - deve comentar partes de código. Comentários específicos podem ser colocados perto das linhas a que se referem, mas esses comentários ainda estão se referindo ao código maior. Eles não descrevem o que / por que a linha faz - eles descrevem o que faz nesse código e / ou por que é necessário nesse código.

Portanto, não são as linhas que devem ser comentadas, mas pedaços maiores de código. Cada pedaço de código deve ser comentado? Não. Harold Abelson disse que "os programas devem ser escritos para que as pessoas leiam, e apenas acidentalmente para as máquinas executarem ". Mas os comentários são apenas para as pessoas lerem - a máquina não os executa. Se seus padrões de codificação forçarem a escrever comentários redundantes em cada linha / pedaço de código, você não estará apenas sobrecarregando o desenvolvedor que precisa escrevê-los - você também estará sobrecarregando os desenvolvedores que precisarão lê- los!

Isso é um problema, porque quando a maioria dos comentários que você lê é redundante, você para de prestar atenção neles (porque sabe que eles serão apenas lixo redundante) e depois perde os comentários importantes . Então eu digo - escreva apenas o comentário importante, para que quando alguém vir um comentário no código, ele saberá que vale a pena lê-lo para entender o código.

Idan Arye
fonte
1
Perca os comentários importantes: +1. A frase que começa: "Eles não descrevem" poderia usar alguma reestruturação para facilitar o acompanhamento.
Candied_orange
3

IMHO deve fazer as duas coisas. Comentar cada linha é bobagem, porque você acaba com linhas como

  i++;    /* Increment i */

com absolutamente nenhuma pista de por que você quer incrementar i. Expanda um pouco isso e você terá o estilo típico de comentários Doxygen, que produz uma grande quantidade de verborragia sem fornecer qualquer idéia de para que serve o código ou como ele funciona. (Pelo menos até onde eu já vi: admito que seja possível escrever documentação útil usando um sistema como esse, mas não estou prendendo a respiração.)

OTOH, se você escrever um bom bloco de comentários no início da função (ou qualquer agrupamento que seja lógico), descrevendo o que deve ser realizado e como, se for menos que óbvio, você terá algo útil. Se você é eu, você pode até incluir o código LaTeX para equações relevantes ou referências a artigos, por exemplo: "Isso implementa um esquema WENO para resolver equações de Hamilton-Jacobi, conforme discutido em ..."

jamesqf
fonte
2
+1 para o comentário doxygen: Essa é precisamente minha objeção a incluir a "documentação" doxygen no meu código; 95% do tempo, apenas repete o que já é óbvio na assinatura da função. Também não vi uma única documentação doxygen que valha nada, ainda. Escrever esses comentários perde tempo três vezes: uma vez para escrever os comentários, uma vez para lê-los novamente e uma vez para depurar problemas criados pelo conteúdo antigo dos comentários.
#
1
Você não está se contradizendo? Eu acho que nós dois concordamos que é fundamental para uma função ter um comentário descrevendo o que faz do ponto de vista da caixa preta - "essas entradas entram, a função faz isso e essas saídas saem". Ele forma o contrato entre a pessoa que escreveu a função e as pessoas que a usam. O objetivo do Doxygen é simplesmente padronizar o formato desses comentários de uma maneira que possa ser analisada e tornada pesquisável / indexável. Então, por que você deseja um "bom bloco de comentários", mas não em um formato padrão, legível por humanos e por máquina?
Graham
O uso de um padrão de comentários como JSDoc, JavaDoc e Doxygen destina-se a fornecer documentação legível por humanos e pesquisável, como disse @Graham. A linha de código mencionada nesta resposta não tem nada a ver com Doxygen. Não consigo nem imaginar um conjunto de regras em vigor que analise esse comentário e produza uma entrada na documentação gerada. Quando você olha o Docs for JMI, as Java Standard Libraries, etc., todos são produzidos usando uma ferramenta muito semelhante ao Doxygen. Esse é o objetivo disso. Não é o que está dito aqui
Andrew T Finnell
Não estou inventando isso - para atender a um requisito canadense, uma empresa em que trabalhei fez os desenvolvedores escreverem um pré-processador que adicionava comentários EXATAMENTE como o exemplo do OP. Eu acho que o nosso era "C ADD 1 TO I" ou algo parecido. Era FORTRAN, então os loops eram similarmente recomendados "C LOOP FROM 1 TO 10". O código foi carregado com comentários inúteis. Eu apaguei toda essa porcaria enquanto mantinha o código. Ninguém nunca disse nada para mim.
Tony Ennis
2

É hora de trazer de volta os fluxogramas! (não realmente, mas espere um minuto)

Outro dia, encontrei meu antigo modelo de fluxograma. Eu o usei apenas para trabalhos de casa e piadas (você precisa amar um bom fluxograma bobo). Porém, mesmo nessa época, a maioria dos programadores comerciais que ainda usavam fluxogramas os gerava automaticamente a partir do código (o que prejudica completamente o objetivo original do fluxograma, que era auxiliar na criação de um código melhor e bastante útil no código da máquina. No entanto, com linguagens de nível superior, o fluxograma mudou de muleta para hoble. Por que? A abstração do fluxograma era igual ao código.Os comentários mostrados são um hobble, pois estão no mesmo nível de abstração do código. Os bons comentários estão em um nível diferente de abstração do que o código.A maneira mais fácil de fazer isso é usar comentários para o motivo, enquanto o código lida com o quê.

hildred
fonte
Lamento informar que os fluxogramas nunca desapareceram.
Ant
Bons comentários estão em um nível diferente de abstração que o código . Ouça ouça!
candied_orange
1
Embora possa ser um conselho decente, não parece abordar a pergunta que foi feita, exceto, talvez, uma única frase.
Bryan Oakley
0

Vou responder à pergunta como indicado:

Dado tudo isso, é possível escrever bons padrões de codificação que capturam essa idéia?

Sim. WYSIWYG. Um bom padrão de codificação é literalmente " é claro para o leitor o que o código a seguir faz e por quê ".

Em outras palavras, meus comentários de revisão de código sobre a legibilidade do código literalmente, 1-1, surgem do meu estado mental de

Eu, como leitor, (melhor ainda, como um padrão mínimo, um modelo mental de um leitor menos experiente, mas razoável), não entenderia o propósito ou o método de trabalho do código a seguir

Geralmente, as pessoas são fáceis de entender "isso precisa de mais legibilidade" quando ouvem "Eu, como desenvolvedor sênior, que você espera que respeite como não sendo burro, não entendi a primeira vez que entendi esse código ou por que ele está lá ou o que ele faz, então precisa ser explicado ".

Isso muda o discurso de "você não seguiu um padrão sem sentido" para "seu código tem uma deficiência específica de legibilidade, levando a um problema prático ".

Um segundo padrão que precisa ser explicitado é o "teste de emergência às 2h".

Seu backup, que não possui esse código, pode descobrir qual é o problema do código ao depurá-lo durante uma ligação de emergência de produção às duas da manhã, quando você está de férias nos Andes chilenos sem telefone celular?

Isso pode parecer subjetivo, mas é realmente fácil de medir: chame um membro da equipe júnior aleatório, que seria de esperar que fosse a pessoa a depurar à noite em emergência de produção, e peça que expliquem como o código não comentado funciona e por que é lá.

DVK
fonte
0

Esta resposta abordou a maioria dos problemas, porém há uma coisa importante.

Eu gostaria de capturar uma idéia ao longo das linhas de: considere um comentário para cada linha, sequência, instrução, seção, estrutura, função, método, classe, pacote, componente, ... de código.

Existem ferramentas para gerar documentação a partir do código, como por exemplo doxygen. Se você usar essas ferramentas, faz sentido comentar arquivos, funções, classes etc. Mesmo que o nome da função seja auto-explicativo, continuo fazendo isso por consistência, porque as pessoas que lerem a documentação ficarão agradecidas.

BЈовић
fonte
1
Mas a "documentação" gerada por essas ferramentas é, pelo menos na minha experiência, geralmente valida menos do que nenhuma documentação, porque não fornece informações úteis ao usuário (e faz com que elas percam tempo tentando extrair os dados não- informações existentes), mas engana os desenvolvedores a pensarem que estão devidamente documentados seu código.
Jamesqf #
@jamesqf Sim, quando metade das funções não está documentada e a outra metade mal. No entanto doxygen pode gerar bastante boa documentação, assumindo que os desenvolvedores comentou adequadamente suas funções, classes, etc.
BЈовић
-1

Muitas das respostas existentes são bem detalhadas, mas achei importante responder:

... [comentários] que serão relevantes em uma revisão por pares, mas não se transformarão em uma atividade irracional da lista de verificação ...

Para mim, os únicos comentários que poderiam ser um padrão podem ser respondidos, perguntando quais comentários são notados quando estão ausentes . Em outras palavras: comentários usados ​​por IDEs ou software de documentação.

Dito isto, isso é subjetivo para quais ferramentas são usadas pelos desenvolvedores, e nem todos os comentários usados ​​por esse software são tão úteis quanto os outros .

Erdrik Ironrose
fonte