Coisas que ninguém te ensina a fazer mas que todo mundo espera que você saiba: escrever documentação
Tags: braziliandevs
Published: 2021-09-12 16:07:03

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]([https://jsdoc.app/](https://jsdoc.app/)) 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](https://www.phpdoc.org/), o [Swagger](https://swagger.io/) do Java e o [Sphinx](https://www.sphinx-doc.org/en/master/), 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).

![ex1b](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/z37if3ao23xvpflm62fd.png)
 
  

## 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.
![ex2b](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/koh0zmyx3cd8a6ffbp4e.png)
 
 

## 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). 

![ex3b](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/izurpempod06f1lyalo8.png)
 

## 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](https://twitter.com/gwidion) e do [Caio Delgado](https://twitter.com/caiodelgadonew) e colaboração do [João Bueno](https://twitter.com/gwidion). Muito obrigada pela ajuda!