Práticas recomendadas na redação e documentação de comentários

20

Comentar hoje em dia é mais fácil do que nunca. Em Java, existem algumas boas técnicas para vincular comentários a classes, e os Java IDEs são bons em criar shells para você. Idiomas como Clojure até permitem adicionar uma descrição de uma função no próprio código de função como argumento.

No entanto, ainda vivemos em uma época em que frequentemente existem comentários obsoletos ou ruins escritos por bons desenvolvedores - estou interessado em melhorar a robustez e a utilidade dos meus comentários.

Em particular, estou interessado em Java / Clojure / Python aqui, mas as respostas não precisam ser específicas da linguagem.

Existem técnicas emergentes que validam comentários e detectam automaticamente comentários "frágeis" (por exemplo, comentários com números mágicos, frases incompletas etc.) ou comentários incorretos (por exemplo, detecção de variáveis com erros ortográficos ou similares).

E mais importante: existem "políticas de comentários" ou estratégias aceitas por aí? Existem muitos conselhos sobre como codificar - mas e quanto a "como comentar?"

— jayunit100
fonte

40

Os nomes / documentação devem dizer o que você está fazendo.
A implementação deve informar como você está fazendo.
Os comentários devem dizer por que você faz do jeito que faz.

— catraca arrepiante
fonte

6

os comentários também devem dizer por que você não está fazendo de outra maneira - ou seja, importantes escolhas de design - porque futuros mantenedores não terão essas informações de outra maneira.

2

Acredito que muitas vezes um comentário deve dizer o que você está fazendo também. Essa ideia de apenas "por que" comentários é um anti-padrão na minha opinião. É um mito que você possa escrever todo o código com clareza suficiente para que qualquer programador possa entendê-lo rapidamente, e minha experiência é a maioria dos programadores que pensam que escrevem código limpo não. É o mesmo que dizer: "Não preciso nomear essa função descritivamente, porque qualquer pessoa pode simplesmente ler o código na função para ver o que ela faz". - isso também não faz sentido, faz?

— dallin

2

@allin se o seu código não estiver claro sobre o que está fazendo; considere refatorá-lo. caso contrário, adicione um comentário explicando por que é implementado dessa maneira (o que também explica o quão melhor). Sua comparação com nomes descritivos é maçãs / laranjas, um nome descritivo deixa claro onde a função é usada e você pode não ter acesso ao código fonte da função.

— roquete aberração

@ Dallas: "É um mito que você possa escrever todo o código com clareza suficiente para que qualquer programador possa entendê-lo rapidamente", tio Bob gostaria de ter uma palavra com você. - "Não tenho que nomear essa função descritivamente, porque qualquer um pode simplesmente ler o código na função para ver o que ela faz." está fazendo!

— Klaar

14

Isso pode ser controverso, mas meu conselho seria escrever o menor número possível de comentários. Use nomes de classe claros e agradáveis, nomes de variáveis e nomes de métodos. Escreva seu código da maneira mais clara possível; e considere que esse é o atributo mais importante do seu código (exceto que ele atende aos requisitos). Escreva um comentário apenas se você tiver deixado o método o mais claro possível e ainda achar que ele exige mais explicações.

E tenha uma prática organizacional, que sempre que alguém mudar de classe de alguma forma, precisará garantir que os comentários ainda estejam corretos.

— Dawood diz restabelecer Monica
fonte

1

Este é um bom começo, mas acho que para satisfazer a pergunta do OP, você precisará escrever algo que atenda às preocupações reais dele em relação à validação automática.

— Robert Harvey

2

+1 - Eu também acho que os comentários devem ser usados apenas para explicar por que o código foi escrito. Eu sei o que if (a == b) then c();faz, mas se eu não sei por que ele faz - é quando um comentário deve ser usado :) #

— 292 Deco

Deco - eu concordo completamente. Os comentários são bons quando quero entender como um método específico se encaixa no processo como um todo. Em outras palavras, POR QUE você chamaria esse método ou POR QUE ele faz o que faz?

— Dawood diz que restabelece Monica

Além de tornar o código escrito claro, devemos também reter idéias, pensamentos, etc. (no nível do código), usando os comentários do TODO. Por exemplo, se você vê uma função / classe capaz de lidar com o tamanho atual dos dados corretamente, mas potencialmente não conseguirá lidar com a carga após 2 anos, certifique-se de escrever sua observação usando o comentário TODO. Os desenvolvedores futuros realmente apreciarão seus esforços. Nunca tente anotar essas coisas em um documento txt / word separado, enquanto escreve código, ninguém realmente se refere a esses documentos.

— TechCoze

veja também: “Os comentários são um cheiro de código”

— mosquito

5

Não tenho certeza de outras linguagens, mas o python permite que você escreva doctests, que são uma forma de comentários com validação automática. Obviamente, eles não devem ser usados no lugar de testes de unidade reais, mas são um método rápido e fácil de documentar funções específicas que podem não ser tão óbvias quanto deveriam. Eles vêm com o benefício adicional de poder executar os testes de comentários para verificar se os comentários ainda estão corretos (pelo menos a parte deles que contém testes).

— Josh Smeaton
fonte

1

E o Sphinx compara o código com a documentação para fornecer métricas de cobertura.

— S.Lott

3

Um dos locais mais autorizados para descobrir como usar o comentário de código para gerar documentação automaticamente é certamente doxygen . Embora pudesse me dar mais dessas ferramentas.

Isso define o padrão de redação de comentários que deve ser seguido para gerar automaticamente a documentação. No entanto, isso fornece mais estrutura, mas não é validado semanticamente; por exemplo, não é possível verificar se você usou inglês enganoso para descrever o objetivo de uma função!

Embora essa seja a melhor coisa que faz comentários estruturados, pessoalmente sinto que há mais documentação necessária para tornar o código mais sustentável. Algum tempo atrás, havia uma pergunta no P.SE O código pode ser a documentação nas ferramentas de desenvolvedor de código aberto? Com que frequência é? Obviamente, isso também se aplica a projetos não de código aberto.

Para tornar o código mais sustentável - é praticamente mais importante que exista uma documentação externa que ajude a criar uma estrutura de como tratar o código e, em seguida, os comentários dentro do código devem ser restritos para ver

Penso que, se você deseja definir as políticas para escrever comentários, deve incluir como uma abordagem holística incluída no padrão de codificação. Veja o seguinte: Quais podem ser algumas armadilhas na introdução de um guia de estilo e documentação para gerar software em uma equipe de desenvolvimento?

Normalmente, um comentário constitui menos de 5% do código. E, na prática, embora as próprias revisões de código atraiam muito menos atenção (sobre outros aspectos do desenvolvimento), é praticamente difícil que os comentários também sejam revisados.

— Dipan Mehta
fonte

1

Não concordo com a última frase aqui. Acabei de terminar um contrato, trabalhando com um líder de equipe que fez análises muito detalhadas. Suas revisões sempre incluíam os comentários - como eles foram redigidos, se os nomes das variáveis estavam corretos, se eles continham todas as informações que um futuro desenvolvedor poderia querer saber. Em pouco tempo, eu sabia o que ele esperava ver em cada comentário e pude produzir comentários de acordo com seu padrão. Portanto, desde que seja política organizacional ter revisões de código e incluir comentários na revisão de código, isso acontecerá.

— Dawood diz que restabelece Monica

Esse é geralmente o único tipo de comentário que eu escrevo, especialmente para métodos para documentar o que entra e o que sai (eu trabalho com linguagens de tipos vagos).

— DanMan

2

Existem técnicas emergentes que validam comentários e detectam automaticamente comentários "frágeis" (por exemplo, comentários com números mágicos, frases incompletas etc.) ou comentários incorretos (por exemplo, detecção de variáveis com erros ortográficos ou similares).

Existe uma técnica bem conhecida - é chamada de "revisão de código" e tem uma irmã chamada "programação de pares". Não espere nada "automagicamente" aqui.

E mais importante: existem "políticas de comentários" ou estratégias aceitas por aí? Existem muitos conselhos sobre como codificar - mas e quanto a "como comentar?"

"Código completo" contém não apenas tudo sobre como codificar, mas também capítulos sobre "como comentar", especialmente sobre como escrever código de auto-documentação.

— Doc Brown
fonte

+1 para o código completo. O Código Limpo de Robert Martin também tem um bom capítulo sobre como escrever elogios úteis. Eu não tenho certeza sobre o mundo Java, mas em .NET mundo que temos ReSharper, que pode 'automagicamente' referências Validar para elementos de código nos comentários :)

— MattDavey

0

Específico para Java, uma fonte que eu gostei é o Oracle How to Write Doc Comments para a Javadoc Tool :

Este documento descreve o guia de estilo, as convenções de marca e imagem que usamos nos comentários da documentação para programas Java escritos na Java Software, Sun Microsystems.

E Item 44: Escreva comentários de documentos para todos os elementos expostos da API :

Para que uma API possa ser usada, ela deve ser documentada. Tradicionalmente, a documentação da API era gerada manualmente, e mantê-la sincronizada com o código era uma tarefa árdua. O ambiente de programação Java facilita essa tarefa com o utilitário Javadoc. Javadoc gera documentação da API automaticamente a partir do código-fonte, com comentários de documentação especialmente formatados, mais conhecidos como comentários de documentos.

do Effective Java 2nd Edition .

— EGHM
fonte