Como posso lidar com um membro da equipe que não gosta de fazer comentários no código?

Os comentários por si só não contribuem para um código melhor, e apenas pressionar por "mais comentários" provavelmente lhe dará pouco mais do que /* increment i by 1 */ comentários de estilo.

Então pergunte a si mesmo por que você quer esses comentários. "É a melhor prática" não conta como um argumento a menos que você entenda o porquê.

Agora, a razão mais notável para usar comentários é para que o código seja mais fácil de entender e quando as pessoas reclamam da falta de comentários, eles são papagaios sem noção ou têm dificuldade em entender o código em que estão trabalhando com.

Portanto, não reclame sobre comentários ausentes: reclame sobre códigos ilegíveis. Ou, melhor ainda, não reclame, continue fazendo perguntas sobre o código. Para qualquer coisa que você não entende, pergunte à pessoa que a escreveu. Você deveria estar fazendo isso de qualquer maneira; com código ilegível, você só fará mais perguntas. E se você voltar a um trecho de código mais tarde, e não tiver certeza de que lembra corretamente o que ele faz, faça a mesma pergunta novamente.

Se os comentários puderem ser corrigidos, e seu colega tiver um cérebro funcional, ele perceberá que o código é muito mais fácil do que fazer perguntas estúpidas o tempo todo. E se você não puder fazer perguntas, então talvez esse código já esteja perfeitamente legível, e é você quem é o culpado - afinal, nem todo código precisa de comentários.

Na frente de habilidades das pessoas, evite parecer condescendente ou acusador a todo custo; seja sério e honesto sobre suas perguntas.

Conheci muitos desenvolvedores que tiveram problemas ao escrever código de autodocumentação ou comentários úteis. Esses tipos de pessoas muitas vezes carecem de autodisciplina ou experiência suficiente para fazer o que é certo.

O que nunca funciona é "dizer a eles para adicionar mais comentários". Isso não aumentará nem sua autodisciplina nem sua experiência. IMHO a única coisa que pode funcionar é fazer revisões de código freqüentes & sessões de refatoração. Quando um desenvolvedor concluir uma tarefa, permita que ele explique todas as partes do código que você não entende. Imediatamente refatore ou documente o código de tal forma que os dois entendam 6 meses depois.

Faça isso por um período de alguns meses, pelo menos duas vezes por semana. Se você tiver sorte o suficiente, os outros desenvolvedores aprenderão através dessas sessões para que você possa reduzir a frequência de revisão.

Estou surpreso que ninguém tenha mencionado as revisões de código ainda. Faça revisões de código! Quando ele tem um check-in de má qualidade, não diga apenas "adicionar comentários". Constantemente faça perguntas e faça com que ele lhe diga o que o código dele faz e por quê. Tome notas. Então, no final da revisão do código, dê a ele uma cópia das anotações e diga-lhe para deixar suas perguntas bastante óbvias. Seja por mais comentários ou apenas refatorando seu código para torná-lo de melhor qualidade (de preferência o último, quando possível)

Isso depende do código produzido pelo seu trabalho de equipe. Se você ler o livro Código limpo do Uncle Bob, descobrirá que ele prefere não adicionar comentários ao código. Se o código em si é tão legível quanto deveria ser, então não há necessidade de comentários.

Se não for esse o caso, ou se você precisar de comentários devido a alguma política não-negociável, então a questão principal se torna se somente você deseja que ele / ela escreva comentários, ou se é toda a equipe ou a equipe / líder do projeto. Se é só você, então você deve conversar com seus outros colegas para descobrir por que isso pode não ser tão importante.

Se o líder do projeto não tiver os comentários, você também poderá solicitá-los como parte de integridade , ou seja, se o código enviado não tiver comentários, o trabalho ainda não está concluído. Ele não pode continuar a fazer outro trabalho, até que seu trabalho atual seja concluído e para que os comentários sejam necessários. No entanto, lembre-se de que esse tipo de forçamento provavelmente resultará em comentários horríveis (espere muitos comentários de repetição de códigos).

A única maneira viável na minha humilde opinião é discutir os lucros reais que você e todo mundo recebe dos comentários. Se ele não entende por mera discussão, há sempre o caminho mais difícil também: em vez de deixá-los escrever um novo código, trabalhe com código existente. Se possível, você deve encontrá-los em duas áreas de trabalho diferentes - uma com comentários úteis e outra que não tem comentários. Ter que ler o código não comentado não legível de outra pessoa é uma grande surpresa em relação ao seu próprio trabalho.

Todos nós já estivemos lá uma vez e ficamos zangados com o autor original de alguma fonte de trabalho tão descuidada. É a reflexão adicional de que cada um de nós é também um autor que faz você perceber que deve se preocupar com a legibilidade - portanto, não se esqueça de discutir os resultados com seu colega depois para promover essa reflexão.

Se você tiver um funcionário que não pode seguir as instruções, repreenda-o e certifique-se de que ele não ajudará sua carreira a progredir. Consistência no estilo de codificação é fundamental para uma equipe, e se todo mundo está escrevendo comentários e este não é, isso vai prejudicar o estilo de codificação.

Dito isso, você provavelmente pode ajudá-lo. Na minha experiência, quando alguém protesta que comentar leva muito tempo existe uma barreira psicológica como…

1. Ele é autoconsciente sobre suas escolhas de código / design e não quer colocá-las em prosa. (As revisões de código podem ser úteis para reforçar a autoconfiança de alguém tanto quanto para derrubá-las.)
2. Ele trabalha de forma muito linear e não pensa muito a frente. Comentar é doloroso porque o força a descarregar o código imediato que estava prestes a escrever de sua memória de trabalho para compor sua intenção de uma maneira diferente. (Se isso for verdade, os comentários se tornam muito importantes para a qualidade do código.)
3. Historicamente, as pessoas não entendem seus comentários.

É importante para um programador perceber que os comentários são como testes: Eles não são apenas para uso futuro - Eles são para o próprio programador. Eles o forçam a pensar de maneira diferente sobre sua abordagem.

Nada disso é um substituto para CI, testes ou revisões de código. É apenas uma das muitas partes críticas da codificação que, em si, não é escrita de código.

Obtenha um software de revisão de código e use-o bem.

Nós usamos o Kiln, e nós amamos isso. Nós temos uma política que todo changeset deve ser revisado (embora nós permitimos que os desenvolvedores levantem / aprovem revisões para si mesmos em tags e mesclagens sem conflito (embora a maioria de nós use rebaseif), dessa forma podemos identificar rapidamente changesets sem comentários). / p>

Código que não está claro é a razão para uma revisão de código ser rejeitada. Não importa se a correção é de comentários ou código mais claro, mas o revisor deve ser capaz de compreendê-lo. Alguns desenvolvedores preferem reescrever o código, mas outros (inclusive eu) geralmente acham mais fácil expressar a intenção nos comentários (o código pode mostrar facilmente o que ele faz, mas é mais difícil mostrar o que deve fazer).

Se houver alguma dúvida sobre a clareza do código, o revisor sempre ganha. Claro que o autor entende, porque eles escreveram. Precisa estar claro para outra pessoa.

Usando software como o Kiln, nenhum changeset é esquecido. Todo mundo na minha equipe de desenvolvimento prefere muito dessa maneira. O software de revisão de código teve um enorme impacto na qualidade do nosso código e na qualidade do aplicativo: -)

É fácil para os desenvolvedores ficarem na defensiva com avaliações rejeitadas quando introduzem o software, mas na minha experiência, não leva muito tempo para perceber que as coisas estão melhores dessa maneira e adotá-lo :-)

Edit: Também vale a pena notar, nós tentamos não ter devs explicando código enigmático verbalmente ou em comentários na revisão. Se algo não estiver claro, o melhor lugar para explicá-lo é no código (nos comentários ou por refatoração), depois adicione os novos changesets à mesma revisão.

am I wrong to focus on the code comments or is this indicative of a bigger problem that should be addressed?

Um pouco. Ótimo código não precisa de comentários. No entanto, como você disse, o código dele não é auto-documentado. Então eu não me concentraria nos comentários. Você deve se concentrar em melhorar a habilidade e a habilidade de seus desenvolvedores.

Então, como fazer isso? As sugestões de Doc Brown sobre revisões / refatoração são uma boa ideia. Acho que a programação em pares é ainda mais eficaz, mas também pode ser consideravelmente mais difícil de implementar.

Interessante que a legibilidade aplicada à linguagem natural é medida pela velocidade de leitura e compreensão. Eu acho que uma regra simples pode de fato ser adotada, se um comentário de código em particular não melhorar esta propriedade, ela pode ser evitada .

Por que comentários?

Embora o comentário de código seja uma forma de documentação incorporada, existem várias maneiras nas linguagens de programação de ponta para evitar a programação supérflua "excessivamente documentada" (de código significativo) usando elementos da própria linguagem. Também é uma má idéia transformar código em listagens a partir de um livro de programação, onde instruções individuais são literalmente explicadas de forma quase tautológica (lembre-se do exemplo "/ * incremento i por 1 * /" em respostas já fornecidas), tornando esses comentários relevantes apenas para programadores inexperientes com a linguagem.

Legibilidade do código! = comentários de código

O código legível não requer anotações por comentários. Em cada lugar específico do código, há sempre um contexto de uma tarefa que esse código em particular deve alcançar. Se o propósito estiver faltando e / ou o código fizer algo misterioso = evitá-lo a todo custo. Não permita que hacks estranhos preencham seu código - é um resultado direto da combinação de tecnologias de bugs com falta de tempo / interesse para entender as fundações. Evite código místico em seu projeto!

Por outro lado, Programa legível = código + documentação pode conter várias seções legítimas de comentários, por exemplo para facilitar a geração de documentação de "comentários para API".

Siga os padrões de estilo de código

Engraçado o suficiente, a questão não é sobre por que comentar código, é sobre trabalho em equipe - como produzir código em um estilo altamente sincronizado (que todo mundo possa ler / entender). Você está seguindo algum padrão de estilo de código na sua empresa? Seu principal objetivo é evitar escrever código que requeira refatoração, é muito "pessoal" e "subjetivamente" ambíguo. Então eu acho, se alguém vê a necessidade de usar o estilo de código, há uma série de ferramentas para implementá-lo apropriadamente - começando com a educação de pessoas e terminando com a automação para controle de qualidade do código (numerosas dicas, etc) e controle integrado) sistemas de revisão de código.

Torne-se um evangelista de legibilidade de código

Se você concordar que o código é lido com mais frequência do que está escrito. Se a expressão clara de idéias e pensamentos claramente é importante para você, não importa qual idioma é usado para se comunicar (matemática, código de máquina ou inglês antigo). Se sua missão é erradicar a maneira maçante e feia de pensamento alternativo. , o último é de outro "manifesto") .. faça perguntas, inicie discussões, comece a espalhar livros que provocam o pensamento sobre limpeza de código (provavelmente não apenas algo semelhante aos padrões de design de Beck, mas mais como já mencionado by RC Martin ) que abordam a ambigüidade na programação. Além disso, há uma passagem de idéias-chave (citada no livro de O'Reilly sobre legibilidade)

• Simplifique a nomenclatura, o comentário e a formatação com dicas que se aplicam a cada linha de código
• Refine os loops, a lógica e as variáveis do seu programa para reduzir a complexidade e a confusão
• Ataque problemas no nível da função, como reorganizar blocos de código para executar uma tarefa por vez
• Escreva um código de teste eficaz, minucioso e conciso, além de legível

Cortando "comentando", ainda resta muito (acho que escrever código que não precisa de comentários é um ótimo exercício!). Nomear identificadores semanticamente significativos é um bom começo. Em seguida, estruture seu código agrupando as operações logicamente conectadas em funções e classes. E assim por diante. Um programador melhor é um escritor melhor (claro, assumindo outras habilidades técnicas dadas).

Antes de tudo, sugiro que você refaça sua abordagem sobre os comentários.

Se forem comentários de documentação no nível da API (expostos posteriormente ao público), esse desenvolvedor simplesmente não está fazendo o trabalho dele. Mas, para todos os outros comentários, tenha cuidado.

Na maioria dos casos eu os encontro, os comentários são maus. Eu recomendaria ler o capítulo de comentários de código do "Código limpo", de Robert Martin , para entender bem o motivo.

Os comentários prejudicam seu código de várias maneiras:

1) Eles são difíceis de manter. Você terá que fazer um trabalho extra quando refatorar; Se você alterar a lógica descrita no comentário, também precisará editar o comentário.

2) Eles geralmente mentem. Você não pode confiar nos comentários e deve ler o código. O que levanta a questão: por que você precisaria dos comentários?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

(O hash não é a soma, mas o produto.)

3) Os comentários entopem o código e muito raramente adicionam qualquer valor.

Minha solução: em vez de adicionar mais comentários, tente se livrar deles!

Se um membro da equipe estiver com dificuldades para entender o código de outro membro da equipe (por qualquer motivo); então esse membro da equipe deve ser capaz de descobrir quem escreveu o código original (qualquer sistema de controle de revisão sensato) e deve ser incentivado a pedir ao autor do código para explicá-lo diretamente (por exemplo, caminhar até a mesa, sentar e discutir).

Nesse caso, se a falta de comentários for um problema, a pessoa que não estiver comentando adequadamente o código gastará uma grande quantidade de tempo explicando o que fez; e (se forem inteligentes) começarão a adicionar comentários para evitar gastar tempo com todas essas explicações.

Note que incentivar os membros da equipe a pedirem explicações uns aos outros é valioso por outras razões. Por exemplo, talvez um membro da equipe seja menos experiente e possa aprender com os membros da equipe mais experientes.

Principalmente, incentivando os membros da equipe a pedirem explicações mútuas, você cria um sistema de autoequilíbrio; onde diferentes membros da equipe "ajustam-se automaticamente" um ao outro.

Isso é basicamente uma extensão da resposta do tdammer, mas realiza revisões de código em intervalos regulares.

Fazer com que ele (e outros desenvolvedores) se sentem, trilhem seu código e, mais ou menos, defendam seus superiores e colegas, o que fará de todos melhores codificadores e agregará valor real em um período de tempo relativamente curto. No curto prazo, não dará ao desenvolvedor em questão nenhuma desculpa para, no momento da revisão, comentar adequadamente o seu código.

O código está revisando as boas práticas?

Considerando as opiniões muitas vezes extremas sobre comentários, hesito em ponderar. Isso foi dito ...

What are some arguments that I can present that if you are going to write (unreadable) code that it should be properly documented?

Entender como escrever código legível e que possa ser mantido exige tempo, prática e experiência. Programadores inexperientes (e infelizmente muitos experientes) muitas vezes sofrem com o Efeito Ikea ( PDF ) . Isso é porque eles o construíram e estão intimamente familiarizados com ele, e eles têm certeza de que o código não é apenas ótimo, mas também legível.

Se a pessoa é um ótimo programador, então pouca documentação é necessária. No entanto, a maioria dos programadores não é grande e muito do seu código vai sofrer no departamento de "leitura de legibilidade". Pedir ao programador medíocre ou em desenvolvimento para "explicar seu código" é útil na medida em que obriga-o a ver seu código com um olhar mais crítico.

Isso significa "documentar" o código deles? Não necessariamente. Caso em questão, eu tive um programador semelhante com esse problema no passado. Eu o forcei a documentar. Infelizmente, sua documentação era tão indecifrável quanto seu código e não acrescentou nada. Em retrospectiva, revisões de código teriam sido mais úteis.

Você (ou um delegado) deve sentar-se com este programador e extrair alguns de seus códigos antigos. Não é o novo material que ele conhece apenas trabalhando nisso. Você deve pedir a ele para orientá-lo através do código com interação mínima. Isso também poderia ser uma sessão de "documentação" separada, na qual ele deve explicar por escrito seu código. Então ele deve receber feedback sobre melhores abordagens.

Como um aparte ... algumas documentações às vezes são necessárias, independentemente de quão boa é a "leitura de legibilidade" do código. APIs devem ter documentação, operações extremamente técnicas e complexas devem ter documentação para auxiliar o programador a entender os processos envolvidos (muitas vezes fora do domínio de conhecimento do programador), e algumas coisas como regex'es complexas devem realmente documentar o que você está combinando.

Muitos projetos exigem documentação de código: documento de interface, documento de design, ...

Alguns projetos exigem que tal documentação seja colocada em comentários de código e extraída com ferramentas como Doxygen ou Sphinx ou Javadoc, para que o código e a documentação se mantenham mais consistentes.

Dessa forma, os desenvolvedores precisam escrever comentários úteis no código e esse dever é integrado no planejamento do projeto.

Eu vou dizer o que a maioria das respostas e comentários sugere: você provavelmente precisará descobrir a verdadeira questão aqui ao invés de tentar forçar sua solução percebida.

Você está motivado para ver comentários em seu código; por que ? Você deu um motivo; por que essa razão é tão importante para você? Ele está mais motivado a fazer outra coisa; por que ? Ele vai dar uma razão; por que essa razão é tão importante para ele? Repita isso até chegar ao nível em que o conflito realmente surge, e tente encontrar uma solução com a qual ambos possam viver. Aposto que tem muito pouco a ver com comentários.

Se você seguir um bom padrão de codificação, haverá um número mínimo de comentários necessários. convenções de nomenclatura são importantes. Nomes de métodos e nomes de variáveis devem descrever seu papel.

Meu TL sugere que eu use menos comentários. ele quer que meu código seja compreensível e descritivo.  exemplo simples: nome da variável para o tipo de string que foi usado para o padrão de pesquisa

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

Ame as respostas de revisão de código, mas talvez meu processo ajude um pouco também.

Adoro comentários, mas quase nunca os adiciono ao código na primeira passagem. Talvez seja apenas o meu estilo, mas eu irei atingir a mesma seção de código de 3 a 5 vezes durante o desenvolvimento (refatoração, testes de escrita, etc.).

Sempre que fico um pouco confuso ou sempre que alguém me faz uma pergunta sobre uma seção de código, tento consertá-lo para que faça sentido.

Isso pode ser tão simples quanto adicionar um comentário removendo um conjunto confuso de operações em sua própria função ou pode desencadear um refatorador maior como extrair um novo objeto.

Sugiro que você incentive todos no grupo a "possuírem" que o código seja legível para outras pessoas. Isso significa que toda vez que alguém fizer uma pergunta sobre seu código, você se compromete a fazer uma alteração ou, melhor ainda emparelhar com essa pessoa para fazer a mudança certo!

Pense seriamente em forçar isso como parte de seu "Contrato de Equipe" (e definitivamente criar um contrato se você não tiver um) - assim todos concordaram com ele e você o coloca em uma parede em algum lugar para que não há dúvidas sobre o que você concordou em fazer.

Talvez esse cara precise apreciar a boa disciplina de codificação e por que é importante que outras pessoas entendam o código que ele escreveu.

Eu trabalhei em algumas bases de código realmente horríveis na minha carreira, em que o código era tão mal organizado, os nomes das variáveis eram tão ruins, comentários tão ruins ou inexistentes, que o código prejudicava minha produtividade. Você não pode trabalhar para consertar ou melhorar uma base de código que você não entende, e se ela for escrita de uma forma que seja impenetrável para os novatos, eles passarão mais tempo tentando entendê-la do que realmente trabalhar nela.

Não há melhor professor do que experiência dura!

Cada base de código tem algumas partes horríveis à espreita, partes do sistema que ninguém quer tocar porque tem medo de quebrar alguma coisa, ou não pode fazer nenhum trabalho significativo porque quem escreveu o código já partiu e levaram sua compreensão do código com eles. Se esse código não tiver comentários e não for auto-documentado, isso só piorará as coisas.

Eu sugiro que você ache a parte da sua base de código que é assim, e dê ao seu codificador problemático a responsabilidade por isso. Dê a ele a propriedade, torne-a sua responsabilidade, deixe-o aprender a verdadeira dor de trabalhar em código que não pode ser mantido porque não é bem documentado ou impossível de entender em um curto espaço de tempo. Depois de alguns meses trabalhando nisso, tenho certeza que ele começará a aparecer.

Dê-lhe outro código sem comentários e peça-lhe para entender o código. Pode ser que ele entenda a importância de comentários apropriados.

Este programador faz alguma manutenção de código. Se não, ele deve: verificar qualquer projeto que você não tenha em volta e atribuir sua manutenção a ele.

Normalmente, esses são os projetos mal documentados em que você perde horas tentando entender o que está acontecendo para corrigir o que poderia ter sido fácil de corrigir. Se esse tipo de experiência não o fizer querer documentação atualizada, correta e útil, nada será necessário.

Em um dos meus projetos anteriores faltavam dezenas de comentários (algoritmo, resultados ou algum JavaDoc básico), então eu decidi fazer 130 edições para ele, e-mail de notificação sobre cada questão a cada 4 dias. Depois de 3 semanas ele teve 280 edições, então ele decidiu escrever comentários.

Os comentários têm um objetivo e apenas um objetivo:

Por que esse código faz isso?

Se um comentário não explica por que algo é assim, então ele deve ser removido. Comentários inúteis que confundem o código são menos do que inúteis, eles são ativamente prejudiciais.

Eu tenho o hábito de tornar meus comentários a coisa mais óbvia no meu IDE. Eles são destacados com texto branco sobre um fundo verde. O realmente chamar sua atenção.

Isso ocorre porque o código explica o que algo está fazendo, e os comentários são para por que ele está fazendo isso. Eu não posso enfatizar isso o suficiente.

Um bom exemplo de um comentário:

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

Um mau exemplo:

/* instantiate clsUser */

Se você estiver usando comentários como "seções" de código: Corte seu método de mamute em funções nomeadas menores e úteis e remova os comentários.

Se você está dizendo o que está fazendo na próxima linha: Faça o código auto-explicativo e remova o comentário.

Se você estiver usando comentários como mensagens de aviso: Certifique-se de dizer o motivo.

Para complementar as respostas aqui, eu poderia adicionar "Se você quer que seja feito corretamente, você tem que fazer isso sozinho".

Eu não quero dizer "comentarista de código-fonte", quero dizer, tornar-se um exemplo para demonstrar o que você gostaria que esse outro desenvolvedor fizesse. Eles dizem que mostrar é mais eficaz do que dizer . Se você puder demonstrar o benefício de comentários de qualidade, ou até mesmo mentor deste outro desenvolvedor (na medida em que ele esteja disposto), você pode encontrar mais sucesso na adoção de comentários por código.

Da mesma forma, em casa, há algumas tarefas domésticas que não me importo de fazer. No entanto, essas mesmas tarefas são as tarefas de minha mãe, que devem ser feitas para que ela seja feliz. A mesma situação se aplica ao vice-versa. Acho que você pode ter que aceitar que esse outro desenvolvedor tem prioridades diferentes de você e não concordará com você em tudo. A solução que minha esposa e eu descobrimos é que, para aquelas tarefas de “estimação”, nós apenas temos que fazê-las nós mesmos, mesmo que isso signifique fazer um pouco mais de trabalho por conta própria.

Simples: se o funcionário não fizer comentários, peça para ele pressionar shift+alt+j para comentário automático em cada método simultaneamente ao digitar o código. por favor, faça a revisão do código para evitar esses problemas.