documentação do código: o Guia Completo do iniciante
você está um pouco no seu primeiro trabalho de programação, e as coisas estão ficando mais fáceis. No início, todo o código com que tiveste de lidar pode ter-te confundido e sobrecarregado, mas estás a começar a apanhar-lhe o jeito. Isso é óptimo! Agora você está se perguntando como levar o código que você escreve para o próximo nível. Enquanto há muitas coisas para aprender sobre a sua pilha de programação, muitas das quais irão torná-lo um melhor programador, existem algumas que irão servi-lo, não importa em que pilha você trabalha. Uma delas é a documentação do Código.
muitos desenvolvedores não escrevem documentação suficiente, seja porque não vêem o valor ou porque sentem que não têm tempo. Você não precisa ser um desses desenvolvedores. Com um pouco de tempo e muita prática, você pode adicionar documentação para o seu código que faz da leitura uma alegria de usar para você e qualquer outro que venha junto.
boa documentação vem em muitas formas
quando a maioria dos desenvolvedores pensa em documentação de código, eles pensam em comentários. Os comentários podem ser adições valiosas ao código, mas não são a única definição de documentação. Documentação é qualquer coisa que você escreve além do seu código para ajudar alguém a entender como ele funciona. Você pode não pensar nisso desta forma, mas um bom exemplo de documentação de código é um arquivo README. Um bom exemplo de documentação básica é o Express.ficheiro js README. Ele responde a várias perguntas importantes sobre o framework e lhe diz como você pode incluí-lo em seu projeto, como instalá-lo, e como executar testes.
boa documentação pode vir na forma de documentação API também. Mais uma vez, expresso.o js é um grande exemplo. Esta versão da documentação é mais uma biblioteca de referência para desenvolvedores usando o framework. Você encontrará respostas a perguntas sobre o que as funções individuais fazem e o que os diferentes parâmetros dessas funções significam. Sem essa documentação de qualidade, O Express não teria tantas equipas a usá-la como eles.
e, claro, você pode usar comentários em linha para o código do documento também. Esses tipos de comentários normalmente não são usados para ensinar as pessoas fora de sua própria equipe sobre o código. Em vez disso, eles são úteis para explicar o que está acontecendo em um código particular para seus companheiros de equipe ou para o seu futuro eu.
por que você deve documentar seu código
como mencionado acima, muitos desenvolvedores não entendem o propósito da documentação de código. Eles vão argumentar que um bom código deve ser auto-documentado e que você não deve precisar explicá-lo. Estas pessoas estão, numa palavra, erradas. A verdade é que boa documentação é uma parte essencial de qualquer base de código. Por quê? Porque as pessoas não deveriam ler todo o seu código para entender o que ele faz. “Pessoas” na frase anterior pode se referir a qualquer um, incluindo seu eu futuro.
a verdade é que, muitas vezes, as” pessoas ” que precisarão entender o código depois de escrito são vocês. Esse pouco de lógica que pareceu tão inteligente quando o escreveste há seis meses pode ser difícil de entender hoje. Se seu código está bem documentado, você não precisa passar tempo tentando entender o que ele faz. Vais poder passar alguns segundos a olhar para a descrição e depois voltar ao que estás a trabalhar neste momento.
Se você tiver a sorte de estar trabalhando em código que é usado por dezenas ou centenas de desenvolvedores, boa documentação é ainda mais importante. As vidas de seus usuários serão significativamente melhoradas pelo seu tempo gasto escrevendo boa documentação, e eles vão agradecer por isso. Literalmente!
a chave para lembrar é que uma boa documentação poupa mais tempo do que o necessário para a escrever. Pode ser o teu tempo, ou pode ser o tempo dos membros da equipa, ou mesmo das pessoas que nunca conhecerás. Às vezes, escrever documentação irá até ajudá-lo a reconhecer uma parte do seu código que é muito complicado para que você possa simplificá-lo.
alguns erros de documentação comuns
como um desenvolvedor júnior, você vai ter que gastar tempo aprendendo o que torna a documentação eficaz. A boa notícia é que você pode aprender com as pessoas que foram antes de você para que você possa evitar erros comuns.
Under-Documentation
one common mistake I see with code documentation is to document information that’s already clearly visible. Por exemplo, os desenvolvedores preguiçosos adicionam “documentação” a uma função adicionando um bloco que fornece o nome de uma função, bem como os nomes de cada parâmetro e seus tipos individuais. Este tipo de documentação é inútil! Demora segundos para alguém ler o nome da função e os parâmetros que ela leva. Isso não é documentação, é apenas repetição. Em vez disso, a documentação deve incluir um pouco rápido de informação sobre o que a função faz e como cada parâmetro muda o comportamento da função ou por que ela é necessária.
Over-Documentation
The opposite pattern can also be a serious problem. Para evitar escrever pouca documentação, alguns desenvolvedores gostam de escrever a explicação para cada pequeno pedaço de lógica que está contido em uma função. Documentam meticulosamente todas as razões que levaram à criação da função. Quando terminarem, podem ter passado tanto tempo a escrever a função como a escrever a documentação. O que é pior, a documentação é muitas vezes difícil de entender e leva tanto tempo quanto ler o código. Esse tipo de documentação também é uma perda de tempo. Em vez disso, uma boa documentação dá uma explicação básica tanto do quê quanto do porquê. Se houver algumas partes particularmente complicadas do código para entender, então a documentação deve explicar apenas essas partes.
confiando em testes para documentar
ocasionalmente, você vai encontrar alguém que argumenta que a melhor forma de documentação é testes de unidade. Essa abordagem tem uma grande deficiência: ler os testes unitários é muitas vezes tão difícil de fazer como ler o próprio código. Qualquer desenvolvedor que deseje aprender o que seu código faz terá um grande primeiro passo enquanto eles caçam e lêem todos os testes de sua unidade. Muitos desistirão antes de conseguirem o que pretendem fazer. Embora o teste de unidade seja uma adição valiosa a qualquer base de código, não é um substituto para uma boa documentação.
formas de levar a documentação para o próximo nível
se você trabalha em uma grande base de código, a documentação de código pode ser assustadora, especialmente se você não tem sido diligente em documentar o código até este ponto. Pode parecer que estás a tentar ferver o oceano. Se você tem uma grande base de código, ou uma onde você sabe que boa documentação é crítica, você pode querer investigar ferramentas de documentação automatizada de código. Estas ferramentas simplificam drasticamente o processo de escrever documentação consistente e boa para toda uma equipe. Uma ferramenta como o GhostDoc irá olhar inteligentemente para o seu código e usar modelos estabelecidos pela sua equipa para iniciar a sua documentação com algumas prensas-chave. Ferramentas de documentação automatizadas removem uma das outras razões comuns para se opor à escrita de documentação: leva muito tempo.
uma vez que você tem documentação consistente, Outras ferramentas permitem que você compartilhe essa documentação facilmente. Ferramentas de documentação automatizadas tiram a dor de desenvolver boa documentação para coisas como APIs públicas que o seu código fornece.
começar hoje
escrever grande documentação é muito mais fácil do que escrever código. Ao contrário do código, a documentação não é uma empresa de tudo ou nada. Comece com o objetivo de escrever boa documentação para uma função todos os dias. Esse tipo de prática constrói hábitos saudáveis, e você vai ver o pagamento ao longo da estrada quando você passa muito menos tempo tentando entender partes de sua base de código. Com o tempo, vai começar a sentir-se mal quando escreveres um código que não tem boa documentação. Você vai começar a apontar maneiras de melhorar a documentação para seus colegas de trabalho durante a revisão de código. Um pequeno hábito irá melhorar o código da sua equipa para todo o seu negócio.
Saiba como o GhostDoc pode ajudar a simplificar os seus comentários em XML, produzir e manter a documentação de ajuda de qualidade.
Sobre o autor
Eric Boersma
Eric Boersma é um desenvolvedor de software e gerente de desenvolvimento de que fez de tudo, desde de segurança de TI em produtos farmacêuticos para escrever software de inteligência do governo dos estados unidos para a construção de internacional de equipes de desenvolvimento para organizações sem fins lucrativos. Ele adora falar sobre as coisas que aprendeu ao longo do caminho, e ele gosta de ouvir e aprender com os outros também.
