DEV Community

Cover image for Coisas que ninguém te ensina a fazer mas que todo mundo espera que você saiba: escrever documentação
Juliana Gaioso
Juliana Gaioso

Posted on

Coisas que ninguém te ensina a fazer mas que todo mundo espera que você saiba: escrever documentação

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

ex1b

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

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

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!

Discussion (3)

Collapse
johnmarison2 profile image
Johnmarison

Hi,
Nice to read this blog. Thanks for sharing this blog Juliana

Collapse
danilologic profile image
Danilo

Adorei, salvo!

Collapse
deivaotv profile image
Deividson Sabino

Muito bom o conteúdo