Os comentários são considerados uma forma de documentação?

Quando escrevo pequenos scripts para mim, empilhar meu código com comentários (às vezes comento mais do que codifico). Muitas pessoas com quem falo dizem que devo documentar esses scripts, mesmo que sejam pessoais, para que, se eu os vender, eu estaria pronto. Mas os comentários não são uma forma de documentação?

Não seria isso:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

ser considerado documentação, especialmente se um desenvolvedor estiver usando meu código? Ou a documentação é considerada fora do próprio código?

Comentários são definitivamente documentação. Para a maioria dos projetos, os comentários são (infelizmente) a forma principal (se não apenas) da documentação do projeto. Por esse motivo, é muito importante acertar. Você precisa garantir que esta documentação permaneça precisa, apesar das alterações no código. Este é um problema comum com comentários. Os desenvolvedores costumam "ajustá-los" quando estão trabalhando em um código familiar; portanto, esquecem de atualizar os comentários para refletir o código. Isso pode criar comentários desatualizados e enganosos.

Muitas pessoas sugerem tornar o código auto-documentado. Isso significa que, em vez de comentários, você reestrutura seu código para remover a necessidade deles. Isso pode se livrar da maioria dos comentários "o quê" e "como", mas não ajuda muito com os comentários "por que". Embora isso possa funcionar efetivamente para livrar-se da maioria dos comentários, ainda há muitas vezes em que escrever um comentário é a maneira mais simples e eficiente de documentar um pedaço de código.

Eles são uma forma de documentação, mas lembre-se de que a documentação está nos olhos de quem vê ....

• Para alguns, o código de auto-documentação é suficiente. Mas isso pressupõe um nível de detalhe técnico como cliente. Devemos ter cuidado ao pensar que isso é suficiente, porque nosso ego pode nos dizer "é óbvio o que esse código está fazendo", mas o tempo pode provar o contrário. Também pressupõe que você conheça com antecedência as habilidades do leitor.

• Para aqueles que procuram o código fonte, mas com menos conhecimento técnico, os comentários podem ser aceitáveis. Mas isso pressupõe que alguém esteja olhando o código fonte.

• Se você é técnico, mas não tem tempo para ler todo o código fonte, pode ser necessário um manual técnico .

• Se o usuário não possui habilidades técnicas, mas precisa apenas saber o que está acontecendo, é necessária a documentação do usuário .

Então a verdadeira questão é quem é seu cliente? Se você é, o código ou os documentos auto-documentados são suficientes. Se for para outra pessoa, convém ampliar a forma como documenta.

Sim, os comentários são uma forma de documentação. Se é ou não uma documentação útil para alguém que precisa manter ou atualizar seu código, é uma questão em aberto.

Eu sei que você quis dizer isso como um exemplo descartável, mas coisas como

print $foo; # this prints "bar"

não é útil; apenas adiciona confusão visual. Não documente o óbvio.

Bloqueie comentários no início de um método ou definição de função que descrevam a função ou a finalidade do método (em termos de alto nível ), entradas, saídas, valor de retorno (se houver), exceções (se houver), pré-condições e pós-condições são úteis, mas apenas na medida em que dizem a alguém como a função ou método deve ser usado. Eles não explicam por que a função existe.

Se alguém precisar manter seu código, você precisará documentar os requisitos e o design em algum lugar, o que normalmente não é feito no próprio código-fonte.

Acho que seguir a abordagem de Bob Martin, a partir do Clean Code, geralmente resolve o problema de você pensar que está comentando demais ou comentando e deixando de fora a documentação:

Nós somos autores. E uma coisa sobre os autores é que eles têm leitores. De fato, os autores são responsáveis ​​por se comunicar bem com seus leitores. Na próxima vez que escrever uma linha de código, lembre-se de que você é um autor, escrevendo para leitores que julgarão seu esforço.

... a proporção de tempo gasto lendo e escrevendo é bem superior a 10: 1. Estamos constantemente lendo código antigo como parte do esforço para escrever um novo código.

Em outras palavras, seu código é auto-explicativo sem a documentação? Não existe uma regra definida para isso (a menos que você trabalhe para alguém como a Microsoft, cuja documentação é acessível ao público), é principalmente ajudar o futuro leitor do código que geralmente é você.

A documentação deve documentar o Por que não o Como . O Como deve ser evidente no código, a menos que seja algum truque de otimização arcano ou outra técnica específica de linguagem que não ocorra normalmente.

O Por que provavelmente não deve estar no código, deve estar em outro lugar, como um backlog do produto, vinculado a confirmar comentários com os IDs da história que podem ser pesquisados ​​em um log de alterações ou nome de filial.

Comentários são uma forma de documentação. Uma forma inferior e que sugere que você localizou uma área do seu código que pode ser melhor fatorada.

Parece que você comenta as coisas compulsivamente. Ter outras opções pode ser uma coisa boa. Posso pensar em três formas superiores de documentação:

1) Fatore melhor seu código. Em vez de adicionar um comentário, extraia um método ou função cujo nome seja o texto do comentário que você estava prestes a escrever. Portanto, o código diz o que seu comentário estava prestes a dizer.

2) testes. Essa é a forma de documentação que eu costumo pesquisar. Testes de unidade e testes de aceitação são documentação viva e podem ser lidos facilmente se vários métodos significativos forem usados ​​para expressar intenção, como no ponto 1.

3) Para scripts, a opção --help. É aqui que você pode enlouquecer no documento. Dê exemplos, preveja o que o usuário precisaria.

Em resumo, se você se inclinar a comentar, verifique se há uma maneira de se comunicar com o leitor estruturando melhor o código. Ou existe um teste que comunica por que esse código existe? Se você ainda se sente inclinado a comentar, admita a derrota e faça-o.