Há mais comentários melhores em ambientes de alta rotatividade?

Eu estava conversando com um colega hoje. Trabalhamos no código para dois projetos diferentes. No meu caso, sou a única pessoa trabalhando no meu código; no caso dela, várias pessoas trabalham na mesma base de código, incluindo estudantes cooperativos que entram e saem com bastante regularidade (entre a cada 8 a 12 meses). Ela disse que é liberal com seus comentários, colocando-os em todos os lugares. Seu raciocínio é que isso a ajuda a lembrar onde estão as coisas e o que elas fazem, pois grande parte do código não foi escrita por ela e pode ser alterada por alguém que não seja ela. Enquanto isso, tento minimizar os comentários no meu código, colocando-os apenas em locais com uma solução ou bug não óbvio. No entanto, compreendo melhor meu código em geral e tenho um controle mais direto sobre ele.

Minha opinião nesses comentários deve ser mínima e o código deve contar a maior parte da história, mas o raciocínio dela também faz sentido. Existem falhas em seu raciocínio? Pode desorganizar o código, mas pode ser bastante útil se houver muitas pessoas trabalhando nele a curto e médio prazo.

Comentários não confundem o código.

E quando o fazem, bem, todo IDE decente pode ocultar / dobrar comentários. Idealmente, a história deve ser contada pelo seu código, documento de requisitos, histórico de confirmação e testes de unidade, e não por comentários. No entanto, comentários excessivos só podem prejudicar quando os comentários estão concentrados no como e não no por que, no entanto, essa é uma discussão diferente .

Acho que você e seu colega estão "certos", a diferença é, é claro, que você trabalha sozinho e ela em uma equipe, que geralmente inclui desenvolvedores inexperientes. Você não tem uma filosofia diferente nos comentários, mas requisitos muito diferentes na comunicação do seu código. O argumento "isso me ajuda a lembrar" também pode resultar do fato de que ela lida com muito mais código do que você e, mais importante, do código produzido por pessoas diferentes, cada uma com suas próprias preferências e peculiaridades.

No final do dia, os comentários do código, apesar de suas falhas óbvias, são a maneira mais simples e rápida de comunicar seu código. Dependendo da composição e organização da equipe, pode até ser a única maneira que se aplica ao menor denominador comum. Normalmente, eu me pego seguindo sua filosofia de comentar quando estiver trabalhando sozinho e me ajustando à de seu colega quando estiver trabalhando em equipe, especialmente se for uma habilidade de equipe desequilibrada.

Comentários prolíficos nesse tipo de ambiente estão encobrindo um problema que deve ser resolvido de outra maneira.

Código legível e de qualidade nunca deve precisar de comentários adicionais para explicar o que faz. O único momento para comentar é quando você deseja explicar por que algo foi feito de uma maneira específica. E mesmo assim, esses comentários podem estar no controle de origem, confirmar mensagens.

Então, o problema que ela está resolvendo é que está tendo que trabalhar com alunos que não sabem escrever seu código de maneira legível. Na minha opinião, sobrecarregar o código com comentários é uma solução fraca para esse problema.

Revisões rigorosas de código seriam muito mais eficazes, tanto para manter o código organizado quanto para melhorar os alunos para o futuro, seja na mesma empresa ou em outro lugar.

O problema dos comentários é que eles tendem a ficar fora de sincronia com o código muito rapidamente. Isso significa que geralmente existem comentários errados ou enganosos no código, portanto eles prejudicam a legibilidade mais do que ajudam.

O objetivo é tornar uma base de código fácil de entender e modificar. Você pode fazer isso através do uso liberal de comentários (embora possa encontrar problemas com comentários de dados), ou pode escrever código de auto-documentação (o máximo possível) e usar apenas comentários para explicar o "porquê" não trivial " questões. Qualquer uma das abordagens pode funcionar, mas lembre-se de que para modificar o código, você precisará entender o próprio código, e não apenas os comentários. Portanto, embora os comentários possam ajudá-lo a entender o código, no final do dia você provavelmente ainda precisará entender o código. Com isso dito, eu prefiro a abordagem de código auto-documentável. Parece ser uma maneira mais direta de criar uma base de código limpa.

"Há mais comentários melhores em ambientes de alta rotatividade?"

Eu acho que eles podem ser piores:

• Autores diferentes usarão diferentes estilos e níveis de detalhes e farão menos comentários de atualização por outras pessoas.

• A opinião de "O que precisa ser comentado" muda de pessoa para pessoa.

• Eles continuam a prática de escrever código difícil de ler com comentários para explicá-lo, em vez de código fácil de ler com nomes descritivos.

• Manter seu formato e consistência se torna um trabalho em si.

• Os novos usuários precisam aprender o padrão de 'formato' antes de poder fazer alterações rápidas.

Ponto 1: A clareza é importante em ambientes de alta rotatividade

Ponto 2: Verbosidade não é clareza

Adicionar comentários ao seu código pode ou não melhorar a clareza; isso depende dos comentários que você adicionar. E quando a clareza ideal for alcançada, comentários adicionais tornarão a situação pior, e não melhor.

Embora os comentários sejam um componente de clareza, a qualidade do código é um componente significativamente mais importante. Inteligência é o oposto de clareza . Se a função do código não for imediatamente aparente por meio de uma leitura casual, o código não será particularmente claro e os comentários (não importa quão de alta qualidade sejam os comentários) são um substituto ruim e ineficaz do código claro.

Por exemplo, colocar uma bandeira no bit mais alto de um campo não relacionado pode ser perfeitamente permitido em determinadas circunstâncias, e pode fazer muito sentido do ponto de vista de desempenho em determinadas circunstâncias, mas é sempre uma má idéia com relação à clareza. , mesmo que você comente demais.

Se você precisar explicar em prosa o que seu código faz, considere um dos seguintes: Observe que alguns deles podem afetar o desempenho, mas o desempenho pode não ser tão importante quanto a clareza em certos casos.

• Melhores nomes de variáveis ​​e nomes de funções
• Melhor layout e espaçamento do código
• Remova todos os "truques" que você achou uma boa ideia
• Agrupe o código de acordo com a função conceitual (por exemplo, extraia o código para uma finalidade específica em uma função com nome apropriado, mesmo que você o chame apenas uma vez)
• Use um algoritmo mais direto (se as condições permitirem)
• Use bibliotecas conhecidas para funcionalidade comum

Uma resposta simplificada: "Quanto mais provável a leitura do seu código, maior o ônus de explicar o que você está fazendo". Isso pode ser facilitando a leitura do código, comentando-o, criando documentação formal, seguindo os padrões de estilo ... Observe que pode ser você quem está fazendo a releitura mais tarde, embora certamente também seja verdade para os outros em um ambiente de alta rotatividade.

Há outro ótimo tópico que aborda se os comentários são ou não documentação.

Os comentários são mais úteis em alguns cenários do que em outros. Isso é tão fundamental que me preocupo em como explicar isso no meio de tantas respostas que considero "anti-comentário".

Se seu código não puder ser lido por anos, os comentários serão mais importantes do que se você tiver refatoração frequente de código, propriedade forte de código e análises de código abundantes. Se o seu aplicativo for complexo e usar técnicas que não são imediatamente óbvias para um observador proficiente nesse idioma, os comentários serão mais importantes do que se o sistema fosse um "Olá, Mundo" glorificado. Se a base de código não for tão rigorosa quanto os padrões, os comentários serão mais importantes do que se você estiver trabalhando com seis camadas de controle de qualidade. Se você estiver trabalhando em uma equipe com oito pessoas apenas aprendendo o idioma, os comentários serão mais importantes do que se sua equipe tiver oito Pulitzers de programação. Se você teve uma aplicação extensa no colo,os comentários são mais importantes do que se você pudesse construí-lo limpo do zero.

Na maioria desses cenários, seria melhor corrigir a causa subjacente em vez de aumentar o uso de comentários? Absolutamente. Mas, às vezes, você fica preso a uma base de código que tem mais impressões digitais do que o smartphone da cidade, e a melhor maneira de melhorá-la é tornar as alterações o mais legíveis possível e comentar.

Para o seu problema específico: os comentários não devem ser espalhados a ponto de desorganizar o código. Um parágrafo bem escrito no topo de uma sub-rotina, descrevendo por que uma função existe e talvez por que ela usa essa abordagem, geralmente é a melhor aposta para ajudar o próximo programador a se orientar.