Como posso lidar com um membro da equipe que não gosta de comentar no código?

Um dos membros da minha equipe evita consistentemente fazer comentários em seu código.

Seu código não é auto-documentado, e outros programadores têm dificuldade em entender seu código.

Pedi-lhe várias vezes para comentar seu código, no entanto, ele apenas dá desculpas ou afirma que o fará mais tarde. Sua preocupação é que a adição de comentários leve muito tempo e atrase os projetos.

Que argumento posso apresentar para convencê-lo a documentar adequadamente seu código?

Nessa nota, estou errado ao focar nos comentários do código ou isso é indicativo de um problema maior que deve ser resolvido?

Os comentários por si só não resultam em código melhor, e apenas pressionar "mais comentários" provavelmente fornecerá pouco mais que /* increment i by 1 */comentários de estilo.

Então, pergunte-se por que você deseja esses comentários. "É uma prática recomendada" não conta como argumento, a menos que você entenda o porquê.

Agora, o motivo mais impressionante para o uso de comentários é que o código é mais fácil de entender e, quando as pessoas reclamam da falta de comentários, são papagaios sem noção ou têm dificuldade em entender o código com o qual estão trabalhando.

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

Se os comentários puderem corrigi-lo e seu colega tiver um cérebro funcional, em algum momento ele perceberá que comentar o código é muito mais fácil do que ter você por perto fazendo perguntas estúpidas o tempo todo. E se você não consegue formular perguntas, talvez esse código já esteja perfeitamente legível, e é você quem está com defeito - afinal, nem todo código precisa de comentários.

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

Eu conheci muitos desenvolvedores que tiveram problemas para escrever código de auto-documentação ou comentários úteis. Esse tipo de pessoa geralmente não possui autodisciplina ou experiência suficientes para fazer o que é certo.

O que nunca funciona é "dizer a eles para adicionar mais comentários". Isso não aumentará sua autodisciplina ou experiência. IMHO, a única coisa que pode funcionar é fazer revisões frequentes de código e 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. Refatorar ou documentar imediatamente o código de forma que vocês dois entendam seis meses depois.

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

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

Isso depende do código que o trabalhador da equipe produz. Se você ler o livro Código Limpo do tio Bob, descobrirá que ele realmente prefere não adicionar comentários ao código. Se o código em si for tão legível quanto deveria, dificilmente haverá 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, a questão principal será se é apenas você quem deseja que ele escreva comentários ou se é a equipe inteira ou a equipe / projeto líder. Se for apenas você, converse com seus outros colegas para descobrir por que isso pode não ser tão importante assim.

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

A única maneira viável, na minha humilde opinião, é discutir os lucros reais que você e todos os outros obtêm dos comentários. Se ele / ela não entende isso por mera discussão, sempre há o caminho mais difícil: em vez de deixá-los escrever um novo código, eles trabalham com o código existente. Se possível, você deve encontrar duas áreas de trabalho diferentes - uma com comentários úteis adequados e outra sem comentários. Ter que ler o código não legível e não comentado de outra pessoa é uma grande surpresa no que diz respeito ao seu próprio trabalho.

Todos nós já estivemos lá uma vez e ficamos bravos com o autor original de alguma fonte por trabalhar tão desleixado. É 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 esqueça de discutir os resultados com seu colega posteriormente para promover essa reflexão.

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

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

1. Ele tem consciência de suas escolhas de código / design e não quer colocá-las em prosa. (As revisões de código podem ser úteis para aumentar a autoconfiança de alguém e destruí-la.)
2. Ele trabalha de maneira muito linear e não pensa muito no futuro. Comentar é doloroso porque o obriga a descarregar o código imediato que estava prestes a escrever da 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 que um programador perceba que os comentários são como testes: eles não são apenas para uso futuro - são para o próprio programador. Eles o forçam a pensar de maneira diferente sobre sua abordagem.

Nada disso substitui o IC, os testes ou as revisões de código. É apenas uma das muitas partes críticas da codificação que não é, por si só, a escrita do código.

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

Usamos o Kiln e adoramos. Temos uma política de que todo conjunto de alterações deve ser revisado (embora permitamos que os desenvolvedores aumentem / aprove as revisões para eles mesmos em tags e mesclagens sem conflito (embora a maioria de nós use o rebaseif); dessa maneira, podemos localizar rapidamente os conjuntos de alterações sem análises).

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

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

Ao usar um software como o Kiln, nenhum conjunto de alterações é esquecido. Todo mundo na minha equipe de desenvolvimento prefere assim. O software de revisão de código teve um enorme impacto tanto na qualidade do código quanto na qualidade do aplicativo :-)

É fácil para os desenvolvedores ficarem na defensiva com críticas rejeitadas ao introduzir o software pela primeira vez, mas, na minha experiência, não demoram muito para perceber que as coisas estão melhores dessa maneira e adotá-las :-)

Edit: Também digno de nota, tentamos não fazer com que os desenvolvedores expliquem o código criptográfico verbalmente ou nos comentários da revisão. Se algo não estiver claro, o melhor lugar para explicá-lo é no código (nos comentários ou na refatoração) e adicione os novos conjuntos de alterações à mesma revisão.

Interessante, que a legibilidade aplicada à linguagem natural é medida pela velocidade da leitura e compreensão. Eu acho que uma regra simples pode realmente ser adotada; se um comentário em código específico não melhorar essa propriedade, pode ser evitado .

Por que comentários?

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

No entanto, é a intenção de tentar comentar o código "sub-documentado" (mas sem sentido) que é verdadeiramente "a fonte de todo o mal". A própria existência de código "sub-documentado" é um sinal ruim - ou é uma bagunça não estruturada ou um truque maluco de um propósito místico perdido. Obviamente, o valor desse código é questionável pelo menos. Infelizmente, sempre existem exemplos, quando é realmente melhor introduzir um comentário em uma seção de linhas de código formatadas (visualmente agrupadas) do que envolvê-lo em uma nova sub-rotina (lembre-se da "consistência tola" que "é o hobgoblin das pequenas mentes") .

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

Código legível não requer anotações por comentários. Em cada local específico do código, há sempre o contexto de uma tarefa que esse código específico deve realizar. Se falta um objetivo e / ou código faz algo misterioso = evite-o a todo custo. Não permita que hacks estranhos preencham seu código - é um resultado direto da combinação de tecnologias de buggy com falta de tempo / interesse para entender as bases. Evite código místico no 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 "comentários para API".

Siga os padrões de estilo de código

Curiosamente, a questão não é sobre por que comentar código, é sobre trabalho em equipe - como produzir código em estilo altamente sincronizado (que todo mundo pode ler / entender). Você está seguindo algum padrão de estilo de código em sua empresa? Seu principal objetivo é evitar escrever código que exija refatoração, seja "pessoal" e "subjetivamente" ambíguo demais. Então, eu acho que, se alguém vê a necessidade de usar o estilo de código, há várias ferramentas importantes para implementá-lo corretamente - começando com a educação das pessoas e terminando com a automação para o controle de qualidade do código (numerosos fiapos, etc.) e (revisão) sistemas de revisão de código integrados ao controle).

Torne-se um evangelista de legibilidade de código

Se você concorda que o código é lido com mais frequência do que está escrito. Se uma 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 do pensamento alternativo .. (desculpe , o último é de outro "manifesto") .. faça perguntas, inicie discussões, comece a espalhar livros instigantes sobre limpeza de código (provavelmente não apenas algo semelhante aos padrões de design de Beck, mas mais como já mencionado por RC Martin ) que abordam ambiguidade em programação. Mais adiante, uma passagem de ideias-chave (citada no livro de O'Reilly sobre legibilidade)

• Simplifique a nomeação, comentários e formatação com dicas que se aplicam a todas as linhas de código
• Refine os loops, lógicas e variáveis ​​do seu programa para reduzir a complexidade e a confusão
• Atacar 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 que seja completo 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 operações conectadas logicamente em funções e classes. E assim por diante. Um programador melhor é um escritor melhor (é claro, assumindo outras habilidades técnicas fornecidas).

Estou errado ao focar nos comentários do código ou isso indica um problema maior que deve ser resolvido?

Um pouco. Um ó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 focaria nos comentários. Você deve se concentrar em melhorar a habilidade e habilidade de seus desenvolvedores.

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

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 seu trabalho. Mas, para todos os outros comentários, tenha cuidado.

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

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 ao refatorar; se você alterar a lógica descrita no comentário, também precisará editar o comentário.

2) Eles freqüentemente 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) Comentários desorganizam o código e, muito raramente, agregam valor.

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

Se um membro da equipe estiver com problemas para entender o código de outro membro da equipe (por qualquer motivo); esse membro da equipe deve ser capaz de descobrir quem escreveu o código original (qualquer sistema de controle de revisão são) e deve ser incentivado a pedir ao autor do código que o explique diretamente (por exemplo, vá até a mesa, sente-se e discuta-o).

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

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

Principalmente, incentivando os membros da equipe a pedir explicações uns aos outros, você cria um sistema de auto-equilíbrio; onde diferentes membros da equipe se "ajustam automaticamente" entre si.

Isso é em grande parte uma extensão da resposta do tdammers, mas execute revisões de código em intervalos regulares.

Fazer com que ele (e outros desenvolvedores) se sente, analise o código e defenda-se mais ou menos na frente de seus superiores e colegas fará de todos melhores codificadores e agregará valor real por um período relativamente curto. No curto prazo, o desenvolvedor em questão não terá desculpas para, no momento da revisão, comentar adequadamente seu código.

EDIT: Não sei por que alguém rebaixou minha sugestão - talvez eu tenha dado como certo que os benefícios da revisão de código seriam de conhecimento comum ... consulte este tópico como uma análise da prática pela comunidade:

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

Considerando as opiniões muitas vezes extremas dos comentários, hesito em comentar. Dito isto ...

Quais são alguns dos argumentos que posso apresentar que, se você deseja escrever um código (ilegível), ele deve ser devidamente documentado?

Compreender como escrever código legível e de manutenção requer tempo, prática e experiência. Programadores inexperientes (e infelizmente muitos experientes) geralmente sofrem com o Efeito Ikea ( PDF ). Isso ocorre 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, pouca ou nenhuma documentação é necessária. No entanto, a maioria dos programadores não é ótima e muito do seu código sofrerá no departamento de "legibilidade". Pedir ao programador medíocre ou em desenvolvimento que "explique seu código" é útil, pois o obriga a ver seu código com um olhar mais crítico.

Isso significa "documentar" seu código? 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 adicionou nada. Em retrospecto, as revisões de código teriam sido mais úteis.

Você (ou um delegado) deve sentar-se com esse programador e exibir alguns dos códigos mais antigos. Não são as coisas novas que ele conhece apenas trabalhando nisso. Você deve pedir que ele o guie pelo código dele com interação mínima. Essa também pode ser uma sessão separada de "documentação", na qual ele deve explicar por escrito seu código. Então ele deve obter feedback sobre melhores abordagens.

Como um aparte ... algumas vezes é necessária documentação, independentemente da qualidade da "legibilidade" do código. As APIs devem ter documentação, operações extremamente técnicas e complexas devem ter documentação para ajudar o programador a entender os processos envolvidos (geralmente fora do domínio de conhecimento dos programadores), e algumas coisas como expressões complexas devem realmente documentar com o que você está correspondendo.

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

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

Dessa forma, os desenvolvedores são obrigados a escrever comentários úteis no código e esse dever é integrado ao planejamento do projeto.

Vou declarar o que a maioria das respostas e comentários sugerem: você provavelmente precisará descobrir o problema real aqui, em vez de tentar empurrar sua solução percebida.

Você está motivado para ver comentários no código dele; por que ? Você deu uma razão; por que essa razão é tão importante para você? Ele está mais motivado a fazer outra coisa; por que ? Ele 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 na qual ambos possam conviver. Aposto que tem muito pouco a ver com comentários.

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

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

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

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

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

Sempre que fico um pouco confuso ou sempre que alguém me faz uma pergunta sobre uma seção do código, tento corrigi-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 refator maior, como extrair um novo objeto.

Sugiro que você incentive todos no grupo a "possuir" que seu código seja legível para outras pessoas - isso significa que toda vez que alguém lhe fizer uma pergunta sobre seu código, você se comprometerá a fazer uma alteração - ou, melhor ainda, emparelhar com esse código. pessoa para fazer a mudança naquele momento!

Considere seriamente insistir nisso como parte do seu "Contrato de equipe" (e, definitivamente, crie um contrato, se você não tiver um) - dessa forma, todos concordarão com ele e você o colocará na parede em algum lugar para que não exista ' Não há nenhuma pergunta 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 possam entender o código que ele escreveu.

Trabalhei em algumas bases de código verdadeiramente terríveis em minha carreira, em que o código era tão mal organizado, os nomes de variáveis ​​eram tão ruins, os comentários eram ruins ou inexistentes, que a base de código prejudicou minha produtividade. Você não pode trabalhar para consertar ou melhorar uma base de código que não entende e, se for escrita de uma maneira impenetrável para os novatos, eles gastarão mais tempo tentando entendê-la do que realmente trabalhando nela.

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

Toda base de código tem alguns trechos 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á se afastou e entendeu seu entendimento do código com eles. Se esse código é descomentado e não se auto-documenta, ele só piora as coisas.

Eu sugiro que você encontre a parte da sua base de código assim e dê ao seu codificador problemático a responsabilidade por isso. Dê a ele a propriedade, faça a 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ê a ele mais um código sem comentários e peça para ele entender o código. Pode ser que ele entenda a importância de comentários adequados então.

Este programador faz alguma manutenção de código. Caso contrário, ele deve: verificar se há algum projeto antipático que você possui e atribuir sua manutenção a ele.

Geralmente, 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 faz querer atualizado, a documentação correta e útil não será suficiente.

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

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

Por que esse código faz isso?

Se um comentário não explica por que algo é do jeito que é, ele deve ser removido. Comentários inúteis que bagunçam o código são menos 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 fundo verde. Realmente chamam sua atenção.

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

Um bom exemplo de 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: Divida seu método gigantesco em funções nominais menores e úteis e remova os comentários.

Se você estiver dizendo o que está fazendo na próxima linha: torne o código autoexplicativo e remova o comentário.

Se você estiver usando comentários como mensagens de aviso: não se esqueça de dizer o motivo.

Para complementar as respostas aqui, devo acrescentar "Se você deseja fazer o certo, precisa fazer você mesmo".

Não quero me tornar um "comentarista chefe de código", quero me tornar um modelo 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 orientar esse outro desenvolvedor (na medida em que ele estiver disposto), poderá encontrar mais sucesso na adoção de comentários de código.

Da mesma forma, em casa, há algumas tarefas domésticas que não me importo. No entanto, essas mesmas tarefas são as tarefas "irritadas" da minha esposa ... tarefas que devem ser feitas para que ela seja feliz. A mesma situação se aplica vice-versa. Acho que você pode ter que aceitar que esse outro desenvolvedor tenha prioridades diferentes das suas e não concordará com você em tudo. A solução que minha esposa e eu descobrimos é que, para as tarefas de "irritar os animais", precisamos fazer sozinhas, 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+jpara comentar automaticamente em cada método simultaneamente com a digitação do código. faça a revisão do código para evitar esses problemas.