Como convencer as pessoas a comentar o seu código [fechado]

https://stackoverflow.com/questions/159597

03-07-2019
|

Pergunta

O que são bons argumentos para convencer os outros a comentar o seu código?

Eu observo muitos programadores favorecer a velocidade percebida de escrever código sem comentários sobre deixando alguma documentação para si e para os outros. Quando eu tentar convencê-los que eu começar a ouvir coisas meia cozido como "o método nome / classe deve dizer o que ele faz", etc. O que você diria a eles para mudar as suas mentes?

Se você é contra comentando, você por favor apenas deixar um comentário. Este deve ser um recurso para pessoas que tentam convencer as pessoas a comentar o código, não o contrário. : -)

Outras perguntas relacionadas são: Comentando código , você comentar seu código e Como você gostaria que seus comentários .

Solução

A melhor maneira de convencer uma pessoa é fazê-los perceber isso por conta própria. Torná-los depurar código bem comentado. Ele irá mostrar-lhes o bom comentando olhares como - comentários são nenhum uso a menos que eles realmente transmitir informações relevantes (que é geralmente o "porquê", porque o código descreve o "o quê"). Eles vão perceber como é fácil. Em seguida, deixá-los voltar para algum do seu código antigo. Eles vão perceber o quão difícil é. Você não só têm mostrado a eles o que não fazer, mas o que fazer (o que é mais importante). Você não tem que fazer mais nada. Além do mais, você não tem que tentar e convencê-los verbalmente. Eles simplesmente precisam entender a necessidade de código de comentário na sua própria maneira. Este é, naturalmente, assumindo que o código que precisa ser comentado não é auto-explicativo.

Outras dicas

Apenas comentar o "porquê" e não "o que". Na medida em que eu concordo, deve ficar claro a partir da classe ou método ou nome da variável que faz e que é utilizado para. Refactor onde isso não acontece em vez de comentar isso.

Se você tomar essa atitude, você vai receber comentários, e você receberá comentários úteis. Programadores como para explicar por que eles estão fazendo algo.

Mostre-lhes o seu próprio código de 6 meses atrás. Se eles não podem compreender e descrever exatamente o que ele faz dentro de 2 a 4 minutos, o seu ponto provavelmente foi feita.

A minha opinião:

Eu não faria isso. O método nome / classe deve dizer o que ele faz. Se isso não acontecer, seja o método ou classe está tentando fazer muito, ou é nomeado mal.

Eu sou um fã de comentar o porquê, não o que. Se não está claro por que o código está usando uma abordagem sobre a outra, comentá-lo. Se você tivesse que adicionar uma variável não utilizada hack para contornar um bug do compilador, comentar o porquê. Mas comentários como "// Connect to banco de dados" são sinais de código ruim ou más políticas. Um método chamado ConnectToDatabase () é muito melhor. E se ele tem "// Determinar IP do servidor DB" nele, talvez, que deve ser puxada para um método chamado "DetermineDbServerIPAddress ()".

O projeto pode ser documentada, mas os comentários são um lugar geralmente pobre para esse nível de documentação. Com o conhecimento do design, e alguns comentários sobre o porquê, o que e como deve ser óbvio. Se não, é, em vez de convencê-los a comentar o seu código, levá-los para melhorá-lo.

Talvez seja apenas algo que tem de ser aprendido com a experiência; Especificamente, a experiência de voltar para o seu próprio código, depois de seis meses, e tentando descobrir o que diabos você estava pensando (ou o que você estava ligado) quando você o escreveu. Isso certamente me convenceu de que os comentários não foram uma má idéia.

Dê-lhes algum (~ 500 linhas, mínimo) horrível, descomentei espaguete-código para refatorar. Certifique-se de variáveis ??não são logicamente chamado. Espaço em branco opcional.

E veja como que como ele!

demasiado severa, mas fica dois pontos através de uma vez.

Escreva o seu código bem.
Comentários É assim que você e outros sabe o que significa.

Gostaria de salientar que este código não deve ter se originado a partir deles. Comentários são realmente útil para a compreensão de seu próprio código, meses abaixo da linha, mas eles também são nigh-on essencial para a compreensão de peças complexas de código de outras pessoas. Eles precisam entender que alguém pode ter que entender o que eles estão fazendo.

Um final Edit: Comentário qualidade também é muito importante. Alguns desenvolvedores têm quase proporção de 2: 1 código-to-comentário em seu trabalho, mas que não torná-los bons comentários. Você pode ter surpreendentemente poucos comentários em seu código e ainda ter que fazer um monte de sentido.

Explique o que está fazendo . Sua qualidade de código deve fazer a maior parte deste trabalho para você embora.
Mais importante, explicar por que você está fazendo algo ! Eu já vi muito código que diz exatamente o que algo está fazendo com nenhuma idéia real porque o desenvolvedor (infelizmente me na maioria das vezes) pensei que era uma boa idéia em primeiro lugar.

Lembre-lhes que a leitura do código só pode dizer-lhes o que o código faz , e não o que é deveria para fazer.

Se você ou os outros desenvolvedores não leu código completo (ou Code Complete 2 ) ainda em seguida, parar o você está fazendo e lê-lo.

Uma coisa que standands fora é "A função deve fazer apenas uma coisa e fazê-lo bem". quando tal função é nomeado após a única coisa que ele faz bem o que mais necessidade existe para comentário?

Comentários têm o hábito de ir fora de sincronia com o código que é suposto estar a descrever. O resultado pode ser pior do que não ter o comentário original em primeiro lugar. Não só isso, mas os desenvolvedores sei que os comentários podem envelhecer e não pode ser confiável. Daí eles vão ler o código e discernir por si mesmos o que está realmente fazendo de qualquer maneira! Isso anula meio a ponto de colocar os comentários lá em primeiro lugar.

Tendo dito que o mesmo pode ser verdade de um nome de função, ele pode ter sido bem chamado originalmente, mas horas extras novas operações foram adicionados a ele que não são a que alude o nome.

Todos os comentários parecem fazer separar as linhas de código um desenvolvedor prefere estar mais perto em conjunto para que eles possam ver mais por screenfull. Eu sei que minha própria re-ação a um pedaço de código com muitos comentários que eu tenho que entender. Excluir todos os comentários. Há agora eu posso ver o que o código é até.

No final do dia, se o seu curso para passar o tempo fazer as coisas direito seu tempo é muito melhor gasto refatoração do código para garantir a sua tão reasonablly auto-descrevendo como ele pode ser, em vez de apenas escrever comentários. Tal exercício compensa em outras formas, como identificando pedaços comuns de código.

Vale a pena tendo em mente também que muitos desenvolvedores bons prefiro muito mais escrever torrado limpo C #, Java, o que quer que as linguagens humanas muito menos precisos com todos os pressupostos e ambiguidades que eles têm. Verdadeiros maioria das pessoas com bom senso saberia quanto detalhe é suficiente detalhe, mas bons desenvolvedores não são 'a maioria das pessoas'. É por isso que vamos acabar com comentários como \\adds a to b and store it in c (isso é ok também extremas, mas você começa o ponto).

Pedindo-lhes para fazer algo que odeia fazer e, francamente, não são muito bons em (mesmo se você estiver convencido de que é a coisa certa a fazer) é simplesmente uma batalha já perdida.

Eu não estou sendo sarcástico em você, mas você deve reformular a pergunta a ser Como convencer outros desenvolvedores para trabalhar como uma equipe?

A sério, algumas pessoas assumem que você pode ler sua mente.

Se você é parte de uma equipe ágil, o código é de propriedade coletiva, assim quando você vê descomentada, desajeitado, ou difícil de ler o código, vá em frente e mudança (refactor)-lo para que possa entender isso. Se as pessoas queixam-se, dizer-lhes por que e ser aberto. Que você tenha achado incompreensível, e ninguém é dono do código.

A nossa estratégia é ter sistemáticas revisões de código, e rejeitar código que não está devidamente documentada (através de comentários, nomeação bom funcionamento e organização, etc ...). Se não está claro para o revisor, você voltar para o banco de trabalho, período.

Eu diria que "ontem eu tive que ler um pouco do seu código. Eu era capaz de compreendê-lo, mas menor ou igual a 5 linhas bem escolhidas do comentário explicando como ele alcançou seus objetivos teria permitido me para lê-lo em cerca de um décimo do tempo e, em seguida, eu poderia ter preocupado com a compreensão de um problema em vez. Eu não sou estúpido, e não mais inteligente é porque você pode escrever coisas que são difíceis de entender. Pelo contrário, se você puder 't produzir conjuntos de documentação + código legível, em seguida, você é menos de um desenvolvedor. "

Eu tinha este perfurado em mim há muito tempo: se você escrever algo e alguém de habilidade razoável não pode compreendê-lo, então a culpa é sua, não a sua culpa. Isto aplica-se a escrever nas línguas naturais, e aplica-se à escrita em linguagens de programação.

Tem havido discussões semelhantes sobre comentando. Aqui é o único em quais regras as pessoas seguem ao comentar código: Quais são as suas "regras duras" sobre comentando seu código? . Algumas das respostas também têm muito boas razões pelas quais você gostaria de comentar o seu código.

Mostrar sabedoria em seu desejo para comentários, e eles serão mais propensos a ouvir.

Menos é mais.

enfatizar a qualidade sobre a quantidade.

Na minha equipe, houve um impulso para comentário tudo em certas da API. Alguns desenvolvedores começaram a usar uma ferramenta que iria gerar automaticamente comentários, olhando para os nomes de métodos e assinaturas.

Por exemplo:

/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{

}

Você pode pensar em um maior desperdício de espaço na tela? Você pode pensar em um maior desperdício de ciclos cerebrais do que ler comentários que fornecem nenhuma informação nova?

Se for óbvio a partir da assinatura do método, não diga isso! Se eu posso descobrir isso em poucos segundos, não colocá-lo em um comentário. Como outros já colocá-lo, diga-me por que você escolheu para fazê-lo dessa forma, não o que você fez. Escrever seu código para que ele seja óbvio o que ele faz.

Liderar pelo exemplo. Os desenvolvedores são facilmente seduzidos quando vêem a coisa certa, então vendo práticas sólidas em ação pode incentivá-los a fazer o mesmo. Além disso, você pode incentivar seu grupo a adotar métricas de código que manutenção código de endereço e comentários. Por exemplo, análise de código irá produzir um erro de métodos sem documentação resumo.

O actual padrões de codificação para o meu atual local de trabalho é comentar todas as funções. regras blanked como este são prejudiciais, e nunca deve ser posto em prática. Há situações (e alguns deles comum), onde a adição de comentários remove a legibilidade.

class User {
    getUserName() { /* code here */ }
}

O que é o ponto em adicionar um cabeçalho de função para o pedaço de código acima? O que mais você vai dizer Besdies "recebe o nome de usuário". Nem todas as necessidades de código para ser comentado. Minha regra de ouro é:. Ignorar os comentários se você não está adicionando qualquer informação útil que a assinatura função não

Os comentários devem ser completo, escrito no nível de intenção (por que não como), e raro.

Ao escrever código que tendem a comentar razoavelmente fortemente como uma questão de disciplina. Então, eu vou de volta e tentar eliminar como muitos comentários quanto possível, sem diminuir a inteligibilidade do código. > 80% das vezes isso é tão fácil como extrair um método bem nomeado, isso geralmente resulta em um comentário que apenas duplica a informação no próprio código. Além disso, se há uma seção de código que "necessidades" um I olhar recado para maneiras de simplificar-lo ou torná-lo mais claro.

Código deve ser auto-documentação, e com as técnicas corretas você pode obter 95% do caminho até lá com bastante facilidade. Geralmente eu considero ser um fracasso se existem quaisquer comentários restantes no código que eu check-in.

Depende de quanta energia você tem ...

Eu encontrei uma maneira muito eficaz foi para torná-lo uma parte fixa de pares base de código comentários - pontos para comentários. Se houvesse uma observação que o código foi mal comentou que gostaria de fazer o comentário desenvolvedor, para minha satisfação, que basicamente meanth eles tinham de descrever o suficiente do código para mim entender isso, imprimindo-o e lê-lo. E eu gostaria de fazê-lo também.

Notavelmente este era popular com os desenvolvedores, mesmo que soe dickensian. Duas coisas aconteceram. Primeiro, as pessoas começaram a comentar o seu código. Em segundo lugar, o código mal comentou tornou-se um sinal de que o desenvolvedor não entendo muito bem o que tinham escrito (caso contrário eles teriam descreveu).

A única verdadeira desvantagem foi que os comentários tinha de ser mantido com o código quando foi revisto para correções de bugs etc. Isto era quase impossível de aplicar em uma loja de desenvolvimento real, mas uma vez o suficiente boa prática foi enraizado que tipo dos aconteceu naturalmente.

BTW eu prefiro comentários no próprio código, em vez de um romance de Dostoiévski como uma string doc. O primeiro é uma ajuda útil para programadores subseqüentes. Este último é apenas um longo pedaço de fora do texto da data que enche o docs e engana todo mundo.

Tê-los usar uma API desconhecida, mas fazer a programação em uma máquina conectada não-Internet (se você pode encontrá-los nos dias de hoje) para que eles não têm qualquer acesso a documentação da API. Esta é efetivamente o que eles estão forçando outros desenvolvedores para fazer se eles estão tentando usar o código dos não-documenters!

Você também tem que diferenciar dois comentários diferentes aqui:

comentários API (javadoc ou outro tipo semelhante de documentação): você pode pedir para eles usar seu próprio código em um cenário limite (condições de contorno como objetos nulos ou cadeias vazias ou ...) e ver se eles realmente conseguem lembrar o que faz as suas próprias funções naqueles caso
(É por isso que eu sou para um javadoc completo, incluindo limite de valor )
comentários Internos (dentro do código-fonte): você pode pedir-lhes para explicar qualquer função que tem codificado, basta escolher uma função com um realmente alto nível complexidade ciclomática , e vê-los luta em torno de todos os diferentes fluxos de trabalho de código e decisão ramificação;)

Bem, há sempre a "se você não comentar o seu código, vamos encontrar alguém que vai comentar a deles" abordagem.
Mais gentilmente, diga-lhes que eles são extremamente deixando para baixo o equipe, se eles não documentar e comentar o que estão fazendo. O código não pertence ao indivíduo, a menos que sejam completas lobos solitários. Ele pertence à equipe, o grupo, que quer ser uma empresa ou uma comunidade.

"Código Escrita" = "seqüência de comandos Escrevendo em uma linguagem especial" + "Escrever comentários"

Deve ser auto-evidente ao código comentário ao escrevê-lo ! Você já comentou código que já é de 3 ou 4 meses de idade? (Claro que você tem, e foi tudo o mais, mas divertido!)

Se o seu projeto já está bem documentado, programadores que adicionar um novo código podem ser motivados a comentários de escrita de uma forma similar.

@ James Curran eu concordo 100%! Eu posso ler o código e descobrir o que você disse ao compilador para fazer; mas isso não quer dizer que era sua intenção de fazer o compilador fazer isso. Eu sei que eu não sou um programador arrogent suficiente para acreditar que escrever código toda vez que eu ele faz exatamente o que eu estava tentando fazê-lo fazer. Além disso, muitas vezes eu achar isso me ajuda a pegar erros de lógica bobas no meu código, passando por depois de eu ter escrito isso e tentar explicar o que eu pretendia para o código para fazer.

Uma idéia é apontar que leva menos de um minuto para escrever uma ou duas frases por classe e menos de meio minuto para escrever uma frase por método.

Diga-lhes para documentar suas funções e interfaces com commments Javadoc e, em seguida, para executar o código através de Doxygen para gerar documentação HTML com aparência legal para seu código. O fator frieza pode ser um bom motivador, às vezes.

Eu uso uma técnica sutil:

Eu definir o nível de avisos no projeto para ser relatado como erros. E o nosso servidor de integração contínua está construindo a solução inteira junto com a documentação XML sobre cada um ckeck-in.

Se os desenvolvedores não escrever comentários, a construção falhar! E depois disso, eles tem que escrever nos comentários, então depois de um tempo, eles me acostumei com isso.

Ele não é agressivo em termos de pressão, mas acho que é como boa maneira de corrigir seu comportamento.

Se os desenvolvedores têm de participar em revisões de código e estão expostos a boa comentando eles devem ser capazes de obter a pista. Se eles não vêem a prática como útil, então eles devem obter algum feedback de seus revisores.

Se isso falhar (supondo que você é o supervisor / gerente) torná-lo parte de sua avaliação de desempenho. Se você pode medir, você pode appraise com base nele.

Certifique-se de que ele é um REEXAME comentando que você marca, à medida que os devs passivo-agressivo irá documentar cada última declaração como uma FU não tão sutil.

Eu me tornei um crente firme no que eu chamo Regra de Headrick , o nome de um colega meu que descobriu que uma boa maneira de motivar alguém a fazer alguma coisa é torná-lo doloroso para eles < em> não para fazê-lo.

No seu caso, pedindo a seus desenvolvedores não comentando a gastar uma ou duas horas explicando o seu código, talvez para uma audiência "lento", talvez durante sua hora de almoço "para derrapagens projeto evitar" irá percorrer um longo caminho. As pessoas inteligentes - mesmo os mais teimosos - aprende rápido

Na minha opinião (e eu estou falando sobre Net programação aqui) se você tem que colocar um comentário você falhou em fazer a leitura do código. A resposta é normalmente refactor!

No entanto, se você sentir que você tem que colocar um comentário, então ele deve ser sempre um "porquê" tipo de comentário e não um comentário que explica o que o código faz.

Escrever o que um método / classe vai fazer antes de realmente codificação isso ajuda muito para obtê-lo direito -. E você comentou ele

Somente empregar bons engenheiros que garantem o seu código afirma implicitamente a intenção (usando comentários e outros). Qualquer um que quer um emprego terá que fazê-lo direito. Duro, mas justo, IMHO.

Licenciado em: CC-BY-SA com atribuição

Não afiliado a StackOverflow