Qual é a relação de código / comentário de ouro? [fechadas]

https://stackoverflow.com/questions/111563

02-07-2019
|

Pergunta

Existe uma relação de código / comentário que você considera ser um sinal de boa saúde (ruim) de código?

Você pode dar exemplos de projetos de código aberto que são considerados para ser bem codificado e seu respectivo rácio comentário?

(Eu percebo que há relação é "verdadeiro" para cada projeto e pode muito bem ser projetos de baixa qualidade que apresentam esta proporção áurea teórica. Ainda ...)

Solução

Os comentários devem ser muito raro e valioso, quase sempre expressando o "porquê" e nunca o "como" (a exceção é quando o como é complexa e não é facilmente perceptível a partir do código).

Cada comentário é um indício de que você pode precisar refatorar para fazer do código intenção mais clara. Cada comentário corre o risco de se tornar desatualizados assim que está escrito.

Temos quase não comenta além de comentários XML em nossa xUnit.net projeto , mas algumas pessoas parecem encontrar o código claro e fácil de ler. :)

Outras dicas

Quem tem de código correção de outro programador irá dizer como muitos comentários quanto possível . O grande problema com o código antigo é: ".. Você vê que o código faz você ver que este é o problema, mas você não sabe por que o programador escreveu assim"

Para entender um bug que você precisa saber:

o deve o código de fazer (não o o código faz) e por quê.
O contrato de cada função. Por exemplo, se há uma NullPointerException então onde está o erro? Na função ou na função de chamada?
Em cada corte é descrito como o problema pode ser reproduzido (versão de idioma, sistema operacional, versão do sistema operacional). Por exemplo, temos muitos hacks para um velho Java VM que não é suportado mais. Mas não temos certeza se podemos removê-lo, porque não sabemos como reproduzi-los.

Nós temos uma proporção de 2-3%, o que é muito pouco. Acho que 10% é bom para projetos grandes ou de longa vida.

Desculpe, não há regra de ouro. Frameworks e bibliotecas, por exemplo, exige muito mais comentários porque os programadores serão os clientes e não têm tempo para ler o código de cada vez que precisa chamar um método.

Projectos em que você está escrevendo / lendo o código precisa de menos comentários e deve tentar melhorar a legibilidade do código, em vez de relação de comentário / código.

Atenciosamente

Os comentários não apenas explicar o código - eles também orientar o depurador que está olhando para o pedaço de código que faz algo

Recuperando histórico de pedidos de um cliente ou calcular se um jogador inimigo é visível pode levar dezenas de linhas de código, e até mesmo um programador especialista pode demorar alguns minutos para ter certeza que é o que ele faz. Um comentário que diz "recuperar o histórico de pedidos do cliente" permite que o depurador para não investigar esse código em tudo, se ele sabe que o histórico de pedidos não é o problema.

I comentário tudo o que penso é ambíguo, ou deve ser explicado. Muitas vezes, eu mais comentários. Por quê? Porque você nunca sabe quem vai trabalhar em seu código. Gosto de imaginar uma situação onde eles substituem metade da equipe com macacos que só entendem que quando pressione enter em uma linha, que recebem uma banana. Então, se eles pelo menos aprender a ler, eles não vão mudar minha lógica sem ler os comentários em primeiro lugar.

Caso e ponto:

// Delete the helloworld file
exec("rm -f helloworld.txt")

não terá alterado para:

exec("rm -rf /")

Não, eu sei, mas mesmo alguns boa desenvolvedores são conhecidos por lógica mudança porque isso não parece certo e não porque houve um erro, ou mudança de exigência .

Eu acho que todos podemos concordar que 0 comentários podem geralmente ser considerados código de sub-documentado. Lembre-se que mesmo o código mais auto documentar sempre apenas pode documentar o que é não ; nunca é o que foi intencionalmente deixado de fora, otimizadas, julgado e rejeitado, etc. Você vai ter sempre alguma necessidade de Inglês, basicamente, em seus arquivos de origem, ou você é obrigado a deixar de fora ressalvas importantes e decisões de design.

Estou interessado em saber como estes princípios de som que vocês estão defendendo (com a qual estou de pleno acordo até agora) traduzir em estatísticas de código. Em particular, quais projetos de código aberto são considerados bem (não excessivamente) documentado, e qual é a relação comentário lá.

Eu tenho um muito simples regra de polegar: Se você precisa parar e pensar mais de ~ 15 segundos quando a codificação algum pedaço de código (por exemplo, uma função ou ciclo complexo, etc.), então esse pedaço de código precisa de um comentário.

Ele funciona muito bem para mim. Da próxima vez que você ou alguém em seu nível de compreensão da base de código em geral, corre para aquele pedaço de código, ele (a) vai ver imediatamente por foi feito da maneira que é feito.

LOC / LOcomment = yearsofexp / 5

A minha regra é esta: se há algo que precisa ser dito e o código de pode não ser feito para expressá-lo, então você pode escrever um comentário. Caso contrário, se o código de pode expressar a idéia, então você deve expressar a idéia no código ou de seus testes.

Se você seguir esta regra, em seguida, seu código deve só precisa de comentários quando se está lidando com algum problema inobvious no hardware ou sistema operacional, ou quando o algoritmo mais óbvia não é a melhor escolha. Estes são "isso é estranho porque" comentários, e realmente são apenas mechanism.Most enfrentamento de comentários de tempo no código são realmente apenas desculpas por não escrevê-lo de uma forma mais óbvia, e tais comentários devem ser evitados e, em seguida, excluído.

Mesmo os bons comentários muitas vezes se tornam mentiras ao longo do tempo, para que as informações em não executáveis, lugares não-testáveis ??como comentários devem ser olhou com desconfiança. Novamente, a resposta é a primeira a evitar o comentário, em seguida, excluí-lo.

Meu proporção ideal é zero. No entanto, o mundo é inferior a ideal, então eu aceitar comentários quando não há outra maneira de comunicar uma idéia importante.

Não deve haver comentários lá onde você sente-los necessário. Não mais e não menos.

Bags as partes que você sente que você pode não entender depois de 6 + semanas de intervalo, quando olhando de novo para o código

Eu tento manter comentários no mínimo. Código deve ser auto explainetory e enquanto código fonte tende a mudar os comentários quase sempre permanecem atrás como uma explicação errada.

O código proporção áurea / comentário é a intersecção de

observações necessárias para se lembrar de coisas que você tinha em mente, enquanto a codificação
comentários necessários para lembrar aos outros de coisas que você tinha em mente, enquanto a codificação
comenta o seu cliente está disposto a pagar por (porque bons comentários custar tempo)
interesse do colaborador na produção de código ofuscado por causa da segurança no trabalho (se ele ou ela está a trabalhar para uma empresa onde um desenvolvedor pode fugir com ele)

Isto também mostra por que essa relação é diferente para cada projeto e cada equipe.

Não há razão áurea. O número de observações depende muito da complexidade inerente do código. Se você está apenas escrevendo aplicações CRUD, você provavelmente não precisa de um monte de comentários. Se você estiver escrevendo um sistema operacional ou um RDBMS, você provavelmente terá que comentar mais, como você vai estar fazendo mais complicado de codificação, e será necessário para torná-lo um pouco mais explícito por que você está fazendo as coisas que você está fazendo.

Se você quiser alguns dados reais sobre os rácios de comentário para diferentes idiomas, dê uma olhada Ohloh .

Como um exemplo, você pode olhar para os várias métricas para o Linux Kernel fonte.

Não creio que qualquer um pode dar-lhe figuras, mas deve ser muito maior em arquivos de cabeçalho do que na fonte.

eu esperaria o arquivo de cabeçalho para uma classe para documentar todas as classes / funções / etc accessable publicamente por incluindo o arquivo de cabeçalho. Isso pode ser bastante um monte de linhas para documentar uma função cujo protótipo é uma linha única (não, apenas escolher bons nomes para as funções e seus parâmetros não é suficiente - pode ser, mas muitas vezes não é). Três linhas de comentário para cada linha de código não seria excessivo.

Para código real, seria muito menor. Eu não concordo com os extremistas que pensam que você deve apontar para zero comentários, mas certamente se você acha que precisa de comentários que você deve primeiro considerar se o código poderia ser mais clara.

Pode variar um pouco. Por exemplo, você pode ter código tão bem escrito que os comentários seria apenas um desperdício de tempo.

Você precisa de comentários suficientes para meses mais tarde você pode olhar para o seu código, leia o comentário, e apenas pegar de onde parou, sem muito esforço. Se a história de vida do código não é necessária, não escrevê-lo.

Não existe tal coisa como um bom comentário a relação de código. Nos velhos tempos, algumas pessoas acreditavam que você precisava ter um comentário na cabeça de cada função explicando o que ele faz.

No entanto, com o advento do código de línguas modernas é bastante auto-documentação. Isto significa que as únicas razões esquerda para colocar um comentário no código, quer seja para explicar onde uma decisão excêntrico veio ou para ajudar com a compreensão de um assunto muito complicado.

Não há "proporção áurea". Ele depende da linguagem e da maneira que você escrevê-lo. O mais expressivo seu código, mais ela pode ser auto-documentado - e, portanto, quanto menos comentários que você precisa. Essa é uma das vantagens de interfaces fluentes.

Você não pode impor uma taxa de código fixo / comentários caso contrário você terminar com código atado com barulho como:

// Add one to i
i++;

que apenas nuvens o código.

Em vez disso olhar para a complexidade do código e ver o que você precisa explicar, ou seja squirelly lógica, por que certos números mágicos são usados, que suposições estão presentes sobre os formatos de entrada, etc.

Ligue seus mantenedores mentalidade e pensar o que você gostaria de ver descrito em relação ao código que você acabou de escrever.

HTH.

aplausos,

Rob

Comentários tem 3 usos, IMO:

Explique por o código faz o que faz
Documento da interface de um módulo
Explique por que outras abordagens para um pedaço de lógica não foram tomadas

Se o código está fazendo algo bastante básico de que o por é claro, que deve ser a maior parte do tempo na maioria dos domínios, então os comentários dentro da lógica deve ser mínimo ... até mesmo nenhum se aproximando . Comentários nunca deve ser explicando a o (com possíveis exceções a dizer, por exemplo, que a função é uma implementação do algoritmo de Foo como explicado no Bar Publicação). Se você precisa explicar o que está fazendo, você está fazendo isso mal.

Há uma excelente discussão de comentários de código em Steve McConnells () reservar código completo (eu tenho a primeira edição, mas eu acredito que é agora uma segunda edição link texto )

Em resumo, reforça o que as outras respostas afirmou - devem ser raras e descrever o porque não o como - se você pode refatorar nomes de variáveis ??e método para substituir comentários em seguida, que deve ser prefferred - com a maioria IDE de oferecer algum tipo de intellisense ( ou como eu ouvi uma vez Don Box descrevê-lo como - intellicrack devido à sua adictivness) não há nenhuma razão para nomes Truncar variável / método quando uma versão mais clara iria comunicar a sua intenção mais clara

0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero

um comando implícita "Do What I Mean" com um "sem comentários" comentário?

Não existe tal relação.

Normalmente, comentários só deve estar lá em situações em que algo pode estar genuinamente incerto, como

// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;

Por outro lado, se você está vendendo código para alguém, ele vai precisar como muitos comentários possível. Imagiologia vendendo um motor 3D ou alguns outros jogos Middleware que não tem comentários. Claro, API-documentação etc. são uma grande parte de tal Middleware bem, mas boa comentou código compensa bem. Coisas como "Adicionar 1 a i" ainda é muito spam, mas algo como "CreateDevice () irá verificar primeiro se DirectX 10 está disponível e cair de volta para o dispositivo DirectX 9 se não", pode ser realmente útil, mesmo que seja trivial ver no código.

Geralmente, o código interno geralmente é muito menos comentado do que o código que você vende, mas exceções podem ser aplicadas.

Eu gosto de usar comentando com código de anotar que eu certifique-se é fácil de ler e tem variáveis ??informativas. Dito isto, eu gostaria de tentar escrever cada linha de código para ser informativo como um comentário, se possível. Você deve ser capaz de ter uma forte essência do que o código faz, antes de ler os comentários, ou você está fazendo errado.

entre 3% e 9,5%, mais ou menos

Eu tenho que dizer que eu vim aqui à procura de uma resposta de cerca de 2 dos comentários por 1 linha de código. Mesmo que isso é um exagero é na direção certa! Em vez disso eu vejo as pessoas recomendando o tratamento de comentários como trufas ou outra mercadoria rara. Olhando de uma perspectiva peculiar da academia, foram a qualidade do código é baixa e uso de controle de versão é ainda mais raro, em seguida, trufas gostaria de exortar ninguém para escrever tanto comentários quanto possível, mesmo contra seu próprio julgamento sobre se o comentário é 100% necessário.

Comentários tornar sua vida mais fácil, porque as chances são que você está indo para estar pensando, o que diabos eu estava pensando ao escrever isso!

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

Não afiliado a StackOverflow