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

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

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.

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ã

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.

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.

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.

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.

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.

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.

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.

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 é

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 ").

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.

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 ..."

É 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ê.

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á.

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.

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 .