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

184

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?

Mahbubur R Aaman
fonte
109
Comentar por causa de comentários não melhora o código. Se o código for compreensível (incluindo o porquê) sem comentários, então comente bem.
Martin York
63
Ah, sim, e quando a complexidade de um trecho de código triplicar para resolver uma condição de corrida ou impasse, não comente! Deixe as pessoas resolverem o enigma de por que o código tem que ser do jeito que é e por que ele quebra de maneiras misteriosas se eles fazem alterações experimentais. Todos devem ser um grande mestre de xadrez da concorrência ...
Kaz
12
@ Kaz Sarcasm (espero) não traduz bem para o texto.
deworde
10
@deworde & artjom - sim, isso é sarcasmo. não, não parece tão limpo quanto poderia, mas é claramente sarcasmo.
17
seguindo o princípio de Dale Carnegie, você deve tentar entender por que ele não quer comentar ... você mencionou que ele não quer atrasar o projeto .. então você pode dizer a ele que se ele não comentar os de outros não seria capaz de entender o código e que iria atrasar ainda mais o projeto ..a deve definitivamente ajudar ..
Anirudha

Respostas:

431

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.

tdammers
fonte
269
+1 em "não reclame de comentários ausentes: reclame de código ilegível".
Md Mahbubur Rahman
4
E se a resposta a qualquer pergunta sobre código estiver na mesma linha de "O que você fez para entendê-lo?"
Saul
40
+1: Pressionar para nomes de funções legíveis pode ter benefícios adicionais ... Na Revisão de Código: "Não consigo entender o que xg_jkhsfkasq está fazendo". "Oh, está liberando o buffer de alimentação primário, agora posso liberar?" "Claro, mas hesito em aprová-lo até que você renomeie a função flush_primary_buffer" "Ah, mas ele também está limpando o cache principal, para que o nome seja enganoso" "É O QUE? Não limpe esse cache, ele paralisará o sistema! Enquanto você estiver alterando essa lógica, você se importaria de renomear essa função? "
deworde
18
Eu ficaria preocupado em dar a impressão de que não consigo ler o código. Um gerente não técnico pode perceber que estou constantemente pedindo ajuda a 'Bob' porque o código de Bob é avançado demais para mim. Isso significaria que Bob é um desenvolvedor 'avançado' e não estou pronto para trabalhar no nível dele.
Rob P.
5
@ Rob P. Eu vejo o medo, mas se você não consegue ler o código e se espera que o mantenha, o código não está bem escrito ou você não sabe o suficiente. Se você não sabe o suficiente, precisa perguntar. Se perguntar revelar que o código é simplesmente difícil de ler, pressione para que ele seja corrigido. O truque seria, se você estiver seguindo o caminho da engenharia social, misturar se Bob vai à sua mesa ou você vai à dele, e ser muito ativo em apontar as coisas. Afinal, um gerente non-tech não será capaz de compreender o conteúdo da discussão ...
deworde
114

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.

Doc Brown
fonte
5
Com +1, essa é a única maneira de implementar mudanças em um colega que eu encontrei, sentar com ele e revisar / refatorar ao lado deles. Se você não puder negar uma revisão de código, isso pode ser difícil. Às vezes, quando você está de nível médio você só tem que levantar questões para idosos e se eles não escutam moer o nariz para fora até que você esteja sênior e pode vetar tal lixo
Jimmy Hoffa
1
Revisões de código e programação de pares são a melhor maneira na minha experiência de melhorar o padrão geral de desenvolvedores em uma equipe. Trata-se de compartilhar conhecimentos e habilidades dentro da equipe. Sem isso, você está fazendo os desenvolvedores aprenderem da maneira mais difícil e assumindo que eles saíram da faculdade perfeitos. A falta geral dessa prática em todo o setor é provavelmente a razão pela qual existem tantos desenvolvedores com mais de 10 anos de experiência que não conseguem escrever código legível e bem organizado.
Martin Brown
27

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)

Earlz
fonte
2
+1 - Se você precisar fazer uma pergunta sobre qualquer parte do código, essa parte precisará de um comentário ou de uma refatoração para que a pergunta não precise ser feita por outra pessoa no futuro.
Dunk
+1 As surpresas surpreendentes sobre códigos / pares são tão baixas nas respostas. A implementação de revisões de código no nível da equipe (para não atrair um indivíduo) pode ajudar a resolver o problema (e talvez outros que você nem sabe que tem :). No extremo, você pode implementar uma política de não-solo-push por meio da qual você não pode fazer push, a menos que suas alterações tenham sido revisadas por outro membro da equipe.
21713 Chris Chris
As políticas de revisão de empresa da @ChrisLee na minha empresa não são aplicadas tecnicamente, mas existe uma política que antes de uma história ser marcada como Pronta para Teste, ela deve ser revisada, independentemente de quem fez o trabalho de desenvolvimento. É muito interessante ter de revisão de código quando o CTO faz um check-in embora lol
Earlz
18

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.

Frank
fonte
+1 para discutir os lucros reais dos comentários. Os comentários devem agregar valor ao código-fonte.
Sparky
1
Re: "este tipo de forçar provavelmente resultará em comentários horríveis". Se você não estiver comentando enquanto codifica, o preenchimento dos comentários após a conclusão do código quase sempre resultará em comentários horríveis, independentemente de você acreditar neles. Quando você está codificando, esse é o momento em que você sabe exatamente por que está fazendo algo de uma maneira específica. Esse é o momento de informar aos outros. Se você comentar depois de terminar, é provável que você nem se lembre do que estava pensando quando escreveu o código, então você tende a lançar um comentário inútil apenas para comentar.
Dunk
3
sempre teve um problema com a abordagem desse livro. Os comentários podem ser v. Úteis para explicar um processo / lógica de negócios (ou por que) que nenhuma quantidade de código limpo pode.
bharal
Embora os comentários no código não sejam necessários, deve haver pelo menos a descrição do método, como Javadoc
Danubian Sailor
2
Código Limpo é um livro decente, mas não deve ser tratado como evangelho. Você deve aplicar o bom senso e decidir por si mesmo o que funciona. Não concordo com os conselhos sobre comentários, porque as linguagens de programação são voltadas para expressar o como de um problema com pouca consideração ao porquê. Eu estava escrevendo um código para o Google Shopping que anexa um código de país ao SKU do produto. É óbvio o que o código está fazendo, mas, a menos que você saiba que só pode usar o mesmo código de produto uma vez, mesmo em mercados diferentes, não saberia por que eu estava fazendo isso. O comentário que adicionei esclarece.
GordonM
10

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.

kojiro
fonte
3
Eu não acho que as ameaças necessariamente sejam eficazes, elas podem parecer bullying (mesmo que essa não seja a intenção) e os codificadores costumam ficar ressentidos com os decretos de altos e, neste caso, ele pode apenas cale os calcanhares ainda mais. Pode chegar a isso como último recurso, mas apenas como último recurso.
GordonM
@GordonM Você acha que seria melhor não dizer a um funcionário quando seu comportamento é inapropriado e quais seriam as consequências de um comportamento inadequado continuado?
Kojiro #
Não dizer nada, obviamente, não é uma boa idéia, obviamente, mas ameaçar as pessoas apenas promoverá um clima de medo, especialmente em relação a algo relativamente menor, como estilo de comentário. Se você lhe explicar razoavelmente por que a equipe considera importante comentar, tudo bem. Mas sei que se alguém me ameaçasse com o saco por algo relativamente menor, eu estaria mais inclinado a começar a procurar outro emprego.
precisa saber é o seguinte
@GordonM Na verdade, tomo uma exceção à implicação de que o que eu disse estava ameaçando, mas de qualquer maneira, eu o corrigi.
Kojiro # 14/13
8

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.

Danny Tuppeny
fonte
4

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

Yauhen Yakimovich
fonte
Você pode escrever um código que não precise de comentários apenas por diversão. Isso pode realmente ser um ótimo exercício, mas não se você precisar voltar ao código e não puder realmente mudar nada, porque você não saberá por que essa função funciona, pois talvez houvesse algum cliente que a quisesse assim. É claro que você pode estar nesse talvez 1% do projeto documentado e fundamentado fora do projeto, mas mesmo assim existem decisões que você toma durante a codificação que não são repassadas à documentação. E, francamente ... Quem lê a documentação que não está no código. Certamente não programadores ;-P.
Nux
1
Um bom engenheiro se preocupa com todo o sistema (incluindo a documentação não gerada por codificação) - mas aqui, é claro, nos ocupamos da codificação em geral. Meu argumento é que não ter identificadores no código chamado foo , bar , tmpSomething2 e IamJustTooSmartAssToCare já melhora a situação e reduz a necessidade geral de explicar qual é o código e o que ele faz. O código deve ser escrito com o "modo de reflexão ativado", como uma API bem projetada, lida, entendida, reutilizada e mantida por humanos. Muitos comentários no código que são difíceis de entender são um sinal muito ruim!
Yauhen Yakimovich 01/03
A programação / codificação de BTW de qualquer tipo de lógica específica de domínio na forma de um HACK ou uma correção de erro "temporária" está de fato produzindo "HACKs estranhos" - assim que você tiver muitos deles dentro da caixa preta - espere que eles falhar e atirar de volta. Isso pode ser justificado por prazos nos projetos do "mundo real", etc. mas, na realidade, é apenas um software barato que requer remodelação da lógica do domínio (ou talvez encontrar um novo emprego).
Yauhen Yakimovich 01/03
Concordo que a legibilidade é importante, o que discordo é que você parece dizer "se você priorizar a legibilidade, não precisará de comentários". Isso simplesmente não é verdade. Estive lá feito isso. Raciocinar o que você faz não vem apenas de nomear variáveis ​​de uma maneira que faça sentido. Faça isso, é claro, mas também inclua motivo nos comentários (mesmo que seja na forma de um número de bug / requisito / história em algum sistema externo). É isso que eu estou dizendo.
Nux 4/03/13
"se você priorizar a legibilidade, não precisará de comentários" - sim, é exatamente isso que estou dizendo (e sei que isso não parece fácil de obter). BTW Você tem situações em que a manutenção do histórico completo de confirmação (controle de versão) não é suficiente para refletir sobre "bug / requisito / número da história"? Eu pratico commits há bastante tempo - funciona para mim e permite manter o código vazio da história do desenvolvimento ... o torna menos organizado organicamente.
Yauhen Yakimovich 4/13/13
3

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.

Pete
fonte
A programação em pares é uma excelente ideia, pois fornece a outro programador uma visão do desenvolvimento do código para que eles saibam o que está acontecendo, tornando duas pessoas responsáveis ​​pelo código. também oferece a chance de um dos dois dizer que algo deve ter um comentário porque é fora do comum ou algo que outra pessoa pode mudar porque parece ... "um vazamento de memória", "codificação incorreta", etc., algumas coisas precisam ser comentadas para que outra pessoa no futuro não desfaça algo porque não parece certa.
Malachi
3

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!

Paul
fonte
4
Isso é bobagem. Espero que ninguém acredite que esse estilo pobre de comentário seja útil. Mas você acredita sinceramente que os comentários nunca devem ser usados?
jmk
1
Sim, essa é uma sugestão boba, se o código for incrivelmente legível, eu poderia entender alguns comentários, mas ver comentários deve dizer por que o método está fazendo o que é e onde será usado quando você chegar a mais do que algumas classes. sem motivo para nenhum comentário, eles ajudam a todos.
DBlackborough
3
O importante é lembrar que, embora tudo faça sentido para você no momento, outra pessoa precisará manter seu código em três anos. Não estrague tudo.
Xaxxon
4
@xaxxon Sem mencionar que maçãs, mesmo que essa pessoa possa ser você.
fofo
3
@ mehaase - Não o que, não como, mas por que é o motivo mais importante para adicionar comentários ao código.
Henk Langeveld 26/02
1

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.

Brendan
fonte
1

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?

LJ2
fonte
Quando uma sala cheia de pessoas começar a rir do seu código ilegível, você começará a trabalhar melhor ao codificar e comentar. :) Sou um grande defensor das revisões de código.
Evik James
1
Fazer as pessoas rirem do código na frente de outros colegas não é o caminho a seguir: - \
Danny Tuppeny
1
Se as pessoas que fazem a revisão do código estão rindo, em vez de serem construtivas, precisam treinar tanto quanto um desenvolvedor que não pode escrever código legível. Fazer críticas construtivas ao invés de depreciativas é uma das habilidades sociais que os desenvolvedores geralmente não têm.
Martin Brown
1

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.

Bill
fonte
0

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.

mouviciel
fonte
6
Não, dessa maneira os desenvolvedores precisam escrever alguns comentários. Sua utilidade diminui com a pressão para escrevê-los, geralmente afundando abaixo de zero na região ativamente prejudicial (comentários inválidos são piores que nenhum comentário) se a política for pressionada fortemente.
Jan Hudec
1
@JanHudec - eu concordo com você. É por isso que algum controle deve ser definido. A geração automática garante que, por exemplo, argumentos de função no código sejam os mesmos que nos comentários. Além disso, ter um único PDF em vez de um diretório de arquivos de origem torna a documentação mais legível (ou seja, mais revisável) por mais pessoas.
Mouviciel
2
Bem, não, não. Como você notará no .pdf, que o código realmente faz algo sutilmente diferente do que a descrição diz?
Jan Hudec
1
Talvez minha opinião seja tendenciosa pelo meu domínio, software de espaço crítico, onde tudo é revisado, controlado, verificado, testado duas ou três ou quatro vezes. A geração automática de documentação não suprime inconsistências, mas ajuda a reduzi-las.
Mouviciel
Sim, você é fortemente tendencioso. Em domínios como o que faz sentido, na maioria dos testes de unidade são suficientes para o controle de qualidade e documentar todas as últimas funções seria perda de tempo.
Jan Hudec
0

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.

reinierpost
fonte
0

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
M.S.Nayak
fonte
0

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.

Bill K
fonte
0

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.

GordonM
fonte
-1

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.

Abhishek Gahlout
fonte
12
Eu apenas evitei o botão -1 nisso. A maior parte do código que escrevo tem muito poucos comentários. Eu não acho que as pessoas se queixam de que não é compreensível nos últimos anos, pelo menos. Com muito poucas exceções, se o código precisar de comentários para ser entendido , ele não precisará de comentários, precisará de melhorias para maior clareza. (Obviamente, você deve assumir um entendimento básico da sintaxe da linguagem. Coisas como, em C ++, não saem do seu caminho simplesmente para evitar o uso, reinterpret_cast<>()porque as pessoas podem achar isso confuso; em C #, se ??fizer o que você precisa, use it; etc)
um CVn
2
@ MichaelKjörling: Pode depender muito do tipo de código que você está escrevendo. Se o seu código depende de características pouco conhecidas de uma linguagem ou API, ou você fez algo de maneira contra-intuitiva para evitar um bug obscuro que demorou horas para descobrir, seria muito mais eficaz comentar sobre (possivelmente incluindo um link para um artigo) do que tentar tornar o código "claro" sobre essas informações básicas sem comentários.
LarsH
@ MichaelKjörling: Estou especialmente motivado a dizer isso hoje porque lutei durante o mês passado com uma profunda API GIS. As instalações da API são complexas e não são completamente documentadas. Estamos constantemente enfrentando surpresas, algumas das quais nos atrasam dias de cada vez. Esperar que outra pessoa (ou eu em 6 meses) precise redescobrir essas pepitas para poder trabalhar efetivamente com nosso código seria um enorme desperdício de tempo dessa pessoa. E esses segredos geralmente não podem ser documentados por "aprimoramento para maior clareza" sem comentários.
LarsH
@ LarsH Isso provavelmente se qualificaria como uma dessas "muito poucas exceções" que mencionei no meu comentário. Não sou contra comentar onde isso realmente agrega valor ; mas não é a quantidade de comentários que torna o código fácil ou difícil de ler. Dito isto, com uma API, eu estaria mais inclinado a documentar essas peculiaridades em outros lugares; digamos, em um wiki ou similar. Talvez também adicione um link para a página relevante ao lado de cada uso. Dessa forma, você não precisa procurar outro local que use esse recurso específico da API sempre que o código não funcionar exatamente como o esperado na primeira tentativa.
um CVn 06/02
@ MichaelKjörling: concordou em geral. Se essas exceções são raras ou não, depende do domínio para o qual você está programando e das APIs que você precisa usar. Links / referências são bons para anotações que se aplicam geralmente, não apenas à situação atual. Ninguém quer uma dissertação no próprio código.
LarsH
-1

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.

Arkh
fonte
1
Essa abordagem é mais provável para fazer o programador sair do que treiná-lo da maneira correta de fazer as coisas.
Martin Brown
-1

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.

agilob
fonte
-1

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.

Jonathan
fonte
-2

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.

M. Dudley
fonte
1
Eu diria que mostrar um código mais limpo / refatorar seu código para ser mais legível demonstra uma mudança maior do que colocar montes de comentários no código.
Makoto
Alguém pode me explicar o que eles não gostam na minha ideia ...?
M. Dudley 14/05
-6

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.

peter
fonte
11
"Comentário automático"? Então é daí que todos os comentários "incremento de 1 em 1" vêm? Qual IDE faz isso (para evitar trabalhos onde está sendo usado)?
a CVn
Tentei editar esta em algo legível, mas não tenho certeza se a palavra primeiro deve ter uma vírgula antes ou depois dela. A frase faz comentários primeiro ou primeiro diz em cada método ?
TRiG