Documentando Internamente / Aprendendo / Fixando

Olá amigos devs!

Espero que esse artigo os ajude de alguma maneira assim como me ajuda muito também.

É fato que documentar o nosso código-fonte é algo crucial.

Quando falamos de Documentação Externa:

Pense em manuais de usuário, wikis de projetos, arquivos README, documentação de API gerada automaticamente (como a do Swagger), ou tutoriais em blogs. O objetivo aqui é explicar como usar o código ou a aplicação como um todo, não necessariamente como ele foi construído por dentro.

A documentação externa nos auxilia na comunicação com o público quando a nossa solução é um produto, uma biblioteca ou uma API, de maneira essencial para que os usuários saibam como utilizá-la, e também no onboarding de novos desenvolvedores, quando um novo membro da equipe não precisa ler todo o código para entender como o projeto funciona.

Contudo, o nosso foco aqui é na DOCUMENTAÇÃO INTERNA

Sabe aquele "insight" que às vezes te ocorre de madrugada ou em qualquer outro momento, que você resolve de vez aquele "problema" no seu código, que te atormentava há séculos? Então: esta é a importancia da documentação interna.

Se você pegar o costume de sempre colocar no seu código, em cada trecho que você finalmente elucidou ou criou uma maneira nova de resolver, a explicação de como fez, é um execelente método para você fixar aprendizado, garantir qualidade, e facilitar não só a sua vida como a de qualquer outro dev que vá ler o seu código no futuro.

Utilizando #region / endregion no Vscode é possível você fazer uma documentação localizada porém bem estruturada, com base em code folding / comment folding, um satisfatório efeito de "folding", assim como acontece com as classes, funções etc.

É muito bom poder retrair aquelas tantas linhas que digitamos pra documentar internamente, deixando assim o código praticamente com a cara que ele realmente deveria ter mas sem perder as explicações de tudo.

Nesse trecho do código da aula de Listas em C# do Bootcamp da Akad Seguros, fiz um folding na parte onde se explica porque foi feita uma remoção do item da lista e como isso ajudou a enteder a diferença entre a capacidade da lista (Capacity) a quantidade de itens na lista (Count), que deixa bem clara essa diferença entre um simples Array e o poder e a flexbilidade de uma Lista, apesar desta ser internamente baseada em um Array.

Segue o código:

List<string> listaString = new List<string>();

listaString.Add("SP");
listaString.Add("BA");
listaString.Add("MG");
listaString.Add("RJ");

Console.WriteLine($"Itens na minha lista: {listaString.Count} - Capacidade: {listaString.Capacity}");
listaString.Add("SC");

Console.WriteLine($"Itens na minha lista: {listaString.Count} - Capacidade: {listaString.Capacity}");
listaString.Remove("MG");

#region Removendo um item da lista
// Esta remoção foi feita 
// para podermos entender como a remoção/adição
// de um item numa lista em C# trata a capacidade da lista 
// de forma dinâmica, aumentando-a ou diminuindo-a para se adequar corretamente.
#endregion

Console.WriteLine($"Itens na minha lista: {listaString.Count} - Capacidade: {listaString.Capacity}");

É extremamente satisfatório ver que podemos ter informações de forma detalhada, do tamanho que quisermos, sem deixar escapar os detalhes, porém com uma excelente organização!

Experimentem criar esse hábito e vão perceber como isso facilita o dia a dia e a fixação real do que você está aprendendo!