Olá mundo, como cês tão ein ?

Hoje eu quero falar sobre um tema muito interessante que particularmente curto muito:

DOCUMENTAÇÃO

Vou tentar ser o mais breve possível e mesmo assim compartilhar oque penso e como faço algumas coisas. Deixa ai nos comentários a sua colaboração. falando se concorda os discorda, enfim, vamos conversar. Boa leitura!

Porque documentar algo ?

Sempre que que vou estudar algo novo ou até mesmo revisitar algumas coisas que já fiz a documentação ajuda muito! Porque quando se escreve um código e não documenta ele, todo o conhecimento que você adquiriu ali pode ser perdido e necessário reestudar novamente, convenhamos que ninguém gosta de fazer algo duas vezes.

Então acabei pegando o costume de documentar grande parte das coisas que faço, seja na faculdade ou no trabalho. Tenho minhas colinhas com coisas que acho extremamente importante e que não posso esquecer.

Além desse benéfico de manter o conhecimento palpável, a documentação faz exercitar o seu conhecimento sobre determinado assunto e também ajuda a melhorar o conhecimento de outros. Vamos supor que você está em um time e que lá existem diversos processos para serem feitos, o seu onboarding nessa nova empresa será muito difícil caso não possuam essa documentação para te auxiliar. Entender gitflow, regras de negócio, reuniões, etc.

A documentação vem com o objetivo de ajudar a compartilhar conhecimento entre pessoas!

Tipos de documentação

Depois de um grande tempo eu acabei percebendo que existem alguns padrões de documentações:

• Documentação de código;
• Documentação em código;
• Documentação de estudos;

.... muito mais

Vou falar um pouco sobre esses três porque, são os que possuo mais contato diariamente.

Documentação de código

Essa é a mais famosa! Esse tipo de documentação é a que explica como e porque aquele método existe, como ele é utilizado, como ele funciona, etc (as famosas regras de negócio).

Um exemplo bem massa é um fluxo especifico do seu sistema ex: pagamento, cadastro de usuários, como é armazenado os dados, como o front trata esses dados etc.

Vamos supor que em uma empresa hipotética você está trabalhando em um sistema de cadastro, mas ocorre uma mudança e você foi realocado para a parte de pagamento. Sendo algo que você nunca teve contato antes e nem conhece os fluxos o que vai fazer ? Como vai entender onde pode alterar quando ocorra um problema do sistema ? Oque alimenta seu serviço ?

Essas são respostas que uma boa documentação deve ter.

Ela não vai servir somente nesses casos, quando uma migração de sistemas ou uma mudança no fluxo de dados ali, vai precisar recorrer a doc. Só assim você vai ter certeza do que está mexendo e que não vai zuar o seu sistema.

Documentação em código

Essa é bastante polémica. Muitos defendem e outros tem aversão a esse tipo de documentação.

"Um código bem escrito já é uma documentação"

É uma frase bem comum entre programadores, mas nem tudo é escrito em pedra.

Na minha perspectiva a documentação em código é algo super útil e que ajuda o dev que irá fazer manutenção no futuro entender o que está acontecendo. A questão é escrever um comentário com 10 palavras ou 20 linhas é interessante mas se for realmente necessário.

exemplo tirado do kernel linux

unsigned int trace_call_bpf(struct trace_event_call *call, void *ctx)
{
 unsigned int ret;

 cant_sleep();

 if (unlikely(__this_cpu_inc_return(bpf_prog_active) != 1)) {
  /*
   * since some bpf program is already running on this cpu,
   * don't call into another bpf program (same or different)
   * and don't send kprobe event into ring-buffer,
   * so return zero here
   */
  ret = 0;
  goto out;
 }

 /*
  * Instead of moving rcu_read_lock/rcu_dereference/rcu_read_unlock
  * to all call sites, we did a bpf_prog_array_valid() there to check
  * whether call->prog_array is empty or not, which is
  * a heuristic to speed up execution.
  *
  * If bpf_prog_array_valid() fetched prog_array was
  * non-NULL, we go into trace_call_bpf() and do the actual
  * proper rcu_dereference() under RCU lock.
  * If it turns out that prog_array is NULL then, we bail out.
  * For the opposite, if the bpf_prog_array_valid() fetched pointer
  * was NULL, you'll skip the prog_array with the risk of missing
  * out of events when it was updated in between this and the
  * rcu_dereference() which is accepted risk.
  */
 rcu_read_lock();
 ret = bpf_prog_run_array(rcu_dereference(call->prog_array),
     ctx, bpf_prog_run);
 rcu_read_unlock();

 out:
 __this_cpu_dec(bpf_prog_active);

 return ret;
}

Oque esse trecho de código do kernel linux faz ? A resposta está nele.

Entendemos que o clean code é necessário e que códigos limpos são documentações! Mas existem processos que precisam ser explicitados em código para que QUALQUER pessoal entenda aquilo. Um processo complexo que toca em diversas partes precisam ser explicitados em código isso é um fato!

Precisamos para de demonizar isso falando que irá "sujar o código" é um contexto sensível e que necessita explicação ? Documenta inline mesmo, todo iram agradecer.

Documentação de estudos

Para documentar algo que você esteja estudando é legal também. Normalmente quando estou desenvolvendo algo utilizo o notion para fazer essa documentação, ou crio um /docs no repo e dentro dele coloco .md respectivos a contextos que achei necessário documentar.

Dessa forma no futuro caso eu queria entender novamente oque é um PropType mas da minha forma, bastar ler minha doc resumida! Cada pessoa interpreta de uma maneira então é mais fácil explicar algo no seu linguajar ? Mais fácil explicar algo feito por você para você não ? HAHAHA

Conclusão

A documentação é um dos mais importantes recursos do desenvolvimento de software e isso é um fato! Precisamos compartilhar conhecimentos porque pessoas vem e vão e softwares ficam muito mais complexos e difíceis de entender.

Toda empresa e DEV deve pensar em escalar a sua documentação porque só assim uma tecnologia se mantém viva.