This content originally appeared on DEV Community and was authored by Juliana Gaioso
Documentar ou não documentar o código não é exatamente um consenso na comunidade. Muita gente diz que um código bem escrito é a própria documentação. O argumento contrário diz que se você é capaz de escrever um código legível, então você é capaz de documentá-lo. Ter uma documentação adequada do projeto (que é diferente de comentários soltos ao longo do código) ajuda tanto no onboarding de novos devs (é mais fácil entender como o projeto funciona quando tudo já está documentado) quanto para refatorar códigos que foram escritos já a algum tempo, evitando que ele se torne legado.
Documentation As Code
DaC é uma forma de automatizar a escrita da documentação com as mesmas ferramentas do código que está sendo escrito. Desta forma, a documentação vai sendo escrita junto do código e ao mesmo tempo do código, o que torna a documentação um organismo vivo e continuamente atualizado. Uma das formas de se criar e manter esta documentação é justamente a colocando nos arquivos de código na forma de um comentário especiais (com marcações próprias) que podem ser extraídos por um framework especifico que gera a documentação de uma forma organizada (em HTML, PDF, Markdown e etc).
Framework
Eu pessoalmente recomendo o JSDoc para projetos frontend pela facilidade de usá-lo já com o javascript. Outras linguagens possuem seus próprios frameworks de documentação, como por exemplo o PHPDoc, o Swagger do Java e o Sphinx, do Python.
A documentação geralmente é escrita na forma de um comentário no próprio código com uma marcação e depois é exportada automaticamente para um documento, que pode ser lido pelo time de desenvolvimento, de produto e até mesmo por usuários (em alguns casos).
O que documentar?
Uma forma simples é descrever as partes principais e explicar a funcionalidade das partes menores (ou auxiliares). Fique atento ao paradigma que está sendo usado. Se você usa orientação a objeto, a parte principal será uma classe, e a parte auxiliar será um método. Em programação funcional, a parte principal e as auxiliares serão funções, então descreva a main e explique a utilidade das funções utilizadas na main.
Outro ponto é que a documentação deve falar do negócio, e não do código. Um código bom e limpo é auto-explicável. A função da documentação é explicar a regra de negócio por trás dele e não o código em si.
Como escrever?
Eu pessoalmente acho que cada trecho de documentação deve caber em um tweet. A idéia não é escrever um artigo para cada parte, apenas ajudar a explicar o que acontece ali. No entanto, aqui é interessante procurar os padrões da comunidade da linguagem que você usa. Em Python, o padrão é ser mais extenso e, em alguns casos, até embutir testes nas docstrings.
Tenha sempre em vista quem vai ler a documentação. Se na sua equipe as pessoas de produto e operações também terão acesso ao documento, não é tão legal usar linguagem técnica demais.
O que não documentar?
Algumas coisas devem ser explicadas a nível de código, e não deveriam ir para a documentação do produto por referenciarem apenas a utilização de um código que não é auto explicável (como por exemplo uma RegExp). Quaisquer comentário que só faça sentido junto ao código não deve ir para a documentação. Todos, de forma geral, são uma prática ruim e não devem nunca ir para a documentação (ou produção).
Seguindo o mapa da mina
Caso seu time esteja adotando a escrita de documentação, veja esse texto como um mapa da mina, que vai auxiliar todos a chegar mais rápido nas especificações do software. Escreva com atenção, mantenha o documento sempre atualizado e o mais importante: leia sempre, isso vai te ajudar bastante (especialmente em refatorações).
Para escrever este texto eu tive a revisão do João Bueno e do Caio Delgado e colaboração do João Bueno. Muito obrigada pela ajuda!
This content originally appeared on DEV Community and was authored by Juliana Gaioso
Juliana Gaioso | Sciencx (2021-09-12T16:07:03+00:00) Coisas que ninguém te ensina a fazer mas que todo mundo espera que você saiba: escrever documentação. Retrieved from https://www.scien.cx/2021/09/12/coisas-que-ninguem-te-ensina-a-fazer-mas-que-todo-mundo-espera-que-voce-saiba-escrever-documentacao/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.