A importância de uma boa Documentação

Issue Type: **Bug**

Reproducing the bug:
* Ensure Hot Exit is set to onExit
* Create a new jupyter notebook
* Close or reload the window

Actual: **user is prompted to save**
Expected: ** no prompt, files will be restored on next reopen **

OS Version: Windows/Linux/Mac
VS Code Version: Code Insiders 1.66.0


 <details>
  <summary>Test A/B</summary>
  <p>Details about your test</p>
</details> 

# Changelog

## Descrição curta da atividade

### Trello/Jira URL
*  [Task 123](https://linkmaneiro.com.br)

<!-- Se tiver blocos de código para mostruário -->
`` `php
echo "Seu código aqui";
`` `

### Mudanças
*  {descrição técnica curta da mudança}
*  {descrição técnica curta da mudança}
*  {descrição técnica curta da mudança}
```

Novamente, podemos ver um pouco de organização na documentação que irá gerar o valor necessário para os mantenedores do projeto entender sobre a melhoria e saber o quê exatamente analisar. 

### Escopos de Projeto

Todo começo de freela tem aquela dúvida de "até onde eu devo entregar pra esse cliente?" ou quando você tá documentando um projeto novo na firma, vem aquele "qual é a ideia de um entregável?" e isso tudo vem de um negócio chamado **ESCOPO do FUCKING PROJETO!**

Qualquer coisa que te ajude a homologar e validar o quê exatamente o cliente tá atrás, é uma documentação. Por exemplo, se você tá fazendo uma landing page seria interessante você ter Mapa do Site (sitemap.xml) mostrando o total de paginas, e antes de qualquer XML a ideia é documentar no nosso bom e velho TXT ou MD pra não ser enrolado pelos clientes que pedem cada vez mais.

Ideias de documentação de escopos de projeto:

```markdown
# Landing da Padaria do seu Zé

Cores: #ffccff, #ccffcc #fafafa #cafeee
Tecnologias: HTML, CSS e Bootstrap

* Landing
    * Hero
    * Pães que são produzidos
    * Horário de Funcionamento
    * Newsletter
* Sobre Nós
    * História da empresa
    * História do seu Zé
* Contato
    * Formulário que manda e-mail pro seu Zé
```

Documentação do projeto Open Source: [Basement LMS](https://github.com/danielhe4rt/basement-lms)

```
## Basement LMS

A criação da LMS vai dar ênfase em uma facilidade maior para que outros desenvolvedores Laravel entendam como é a modelagem de tudo.


Essa aplicação ainda está em desenvolvimento, caso você queira integrar ao time, mande um e-mail para os mantenedores!

`` `
danielhe4rt: hey@danielheart.dev
`` `

### Projeto
1. [] Base do Projeto
   1. Tecnologias:
      1. [x] Bootstrap 4/5
      2. [x] Azure Stream 
      3. [x] Docker 
      4. [] Larastan
2. [] Autenticação
    * [x] Métodos base: Sessão
    * [] Métodos custom: Google, Github e Twitch
3. [] Cursos
    1. [] Modelagem Admin
       1. [X] Pagina de Criação de cursos
       2. [X] Pagina de Criação de módulos
          1. [] Ordenação de módulos
       3. [X] Pagina de Criação de Lições
          1. [X] Lições de Video
          2. [X] Lições em Artigos
          3. [] Lições em Quiz 
          4. [] Ordenação de Lições
    2. [] Modelagem User 
       1. [] Pagina inicial com todos os cursos
       2. [x] Pagina principal de um curso
       3. [x] Pagina para assistir o curso
4. [] Subscrição
    1. [] Método de pagamento: 
       1. [] Stripe
       2. [x] GerenciaNet
       3. [] Pagarme
       4. [] Paypal
    2. [] Formulário não pagante: Se não houver condições de comprar, deixa o salve que a gente libera!
5. Gameficação
   1. [] Leveling 
      1. [] Ao assistir uma aula
      2. [] Ao responder um questionário
   2. [] Tabela de EXP: definir um algoritmo de leveling pra não se preocupar com banco
6. Landing Page
   1. [x] Layout Base com integrações

[........] para mais informações, acesse o repo :p
```

Nesses dois exemplos, vimos como é possível abstrair documentações dos diferentes escopos de projeto, e vai da sua ideia entender como fazer isso da melhor maneira. Novamente, a doc tem que ficar claro para **VOCÊ E O CLIENTE!**

### Documentação Técnica

Vamos assumir que você, `joaozinhohe4rt` ou `mariazinhahe4rt` entrou numa empresa onde a code base é ENORME e você não tem tanto acesso ao time para fazer perguntas, não seria interessante ter uma **DOCUMENTAÇÃO** do código? 

Em grandes empresas, é obrigatório entregar uma documentação legível para os clientes sobre como USAR a aplicação, mas poucas empresas lembram da documentação de como a aplicação foi criada ou o porquê aquele código existe e isso é bem grave. 

Recentemente estava fazendo uma implementação do ACL (Access Control List) na minha empresa, onde a ideia é gerenciar quais cargos tem acesso à tal parte da plataforma. Porém, não tinha nenhuma documentação em PT-BR sobre a lib que eu estaria usando, e o time também desconhecia a ferramenta. Com isso eu decidi criar uma pasta dentro do projeto chamada `docs` e junto ao Readme do projeto, começar a documentar o que eu estava fazendo no código.

![Readme Inicial do Projeto](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/o6b62qmlb79rtlot5dor.png)

E quando chegamos na Feature em si, descrevemos o passo a passo do que você deveria saber sobre o que foi implementado. Não existe um padrão, mas isso também conta como algo **MUITO VALIOSO** para a empresa e para as próximas pessoas que forem manter o projeto.

![Documentação técnica](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/85l3ds4qy1pxoo5p77j0.png) 

Nisso, você `joaozinhohe4rt` ou `mariazinhahe4rt` que entrou na empresa, vão ter mais informações quando forem mexer na tal feature e também atualizar a documentação já escrita. Bacana né?

### Blocos de Código

Agora vamos para o mais polêmico de todos para fechar com chave de ouro! O tal do docblock que todos abominam ou amam com todas as forças.

Qual é a ideia de um docblock? Documentar uma função em seus minimos detalhes baseado em sua anatomia. Se liga no exemplo:

```php

/**
 * Função para enviar e-mails com um template boladão pra galera que der like nesse post
 * 
 * @author danielhe4rt - hey@danielheart.dev
 * 
 * @param User $sender
 * @param Template $template
 * @param array $mailList
 * 
 * @return void
 */

public function handle(User $sender, Template $template, array $mailList): void
{
    $sender->send($template, $mailList);
}

```

O docblock é literalmente esse bloco de comentário gigantão ai que diz o quê a função faz e também tem outros beneficios, sendo para os interpretadores te ajudarem na hora do código à te darem uma orientação e também ser intuitivo e descritivo.

Porém como nós podemos ver nos estudos de Clean Code, a ideia é que o código seja auto descritível e não contenha comentários.

```php
public function dispatchMailing(User $sender, Template $template, array $mailList): void
{
    $sender->sendMailTo($mailList)
        ->withTemplate($template);
}

```

Não temos o docblock mas se você souber o bom e velho inglês, você vai saber EXATAMENTE o que está acontecendo ali dentro. Quando existem docblocks em funções, e essas funções são ATUALIZADAS, muitas das vezes é esquecido de verificar se o que o docblock descreve é realmente o que condiz com a função. Então, isso é visto como um problema na maior parte do tempo.

#### O que eu acho de docblocks?

Recentemente comecei um projeto open source e com isso, comecei a fazer minhas pesquisas em outros projetos que eu utilizo no meu dia a dia. Vi que em aplicações finais, o clean code sem comentários é o mais recomendado já que tudo vai estar em constante mudança.

Já nos pacotes que você cria e mantêm para várias pessoas é **ALTAMENTE RECOMENDADO** você usar e abusar de docblocks, já que o projeto será mantido por várias pessoas e deverá ter um critério maior de aceitação nos PR's da vida.


### Conclusão

Documentação é algo muito pouco valorizado no inicio da carreira de um desenvolvedor, porém uma documentação rica em detalhes pode fazer a diferença em todos os quesitos.

Toda documentação pode virar um conteúdo didático, assim como feito nesse post pegando referências de posts de Twitter, Issues e Pull Requests de projetos e até mesmo lendo projetos abertos.

Se você curtiu o conteúdo, deixa aquele likezinho maroto, compartilha no Twitter/IG e marca nois e até a próxima 💜


**Revisores:** Flaubordi e Nandaknwls