É o seu primeiro dia como Tech Lead de um time. Você está super animado e disposto a enfrentar esse novo desafio. Quando começa a analisar o código das aplicações, percebe que não existe um padrão de escrita pré-definido. Metade do código segue uma arquitetura definida por um antigo Tech Lead, mas a outra metade está totalmente fora do padrão. Mesmo o desenvolvedor mais antigo do time, leva muito tempo para realizar as manutenções e os novos integrantes têm uma curva de aprendizado enorme. 

Esses são alguns dos efeitos colaterais de uma aplicação que foi desenvolvida sem a escrita de uma documentação adequada.  
‍
No universo do desenvolvimento de software, a documentação de código é a espinha dorsal que sustenta a manutenção, escalabilidade e colaboração eficaz em projetos. Ela desempenha um papel crucial no ciclo de vida do desenvolvimento, garantindo a compreensão e o crescimento contínuo do código.

Se você não possui o hábito de documentar o seu código e não sabe nem por onde começar, confira abaixo algumas dicas para integrar esse processo à sua rotina, que tanto contribui para a evolução dos projetos e resultados da empresa.
‍

7 dicas para documentar seu código de forma clara e útil:

1. Faça comentários claros e concisos

Comentários bem elaborados são essenciais para descrever o propósito, a lógica por trás do código e sua funcionalidade. Devem ser escritos de maneira clara, concisa e sem ambiguidades, utilizando uma linguagem simples e direta para facilitar a compreensão, tanto para membros atuais da equipe, quanto para futuros desenvolvedores que possam trabalhar no código.

2. Documente funções e métodos

Cada função ou método deve ser acompanhado por documentação específica que descreva seu propósito, os parâmetros que recebe, o que retorna e, se relevante, exemplos de uso. Essa documentação deve ser detalhada o suficiente para permitir que qualquer desenvolvedor entenda como usar a função sem ter que revisar seu código interno.

3. Padronize o estilo

Manter um estilo consistente ao longo do código e da documentação é crucial. Isso inclui a formatação de comentários, uso consistente de linguagem e terminologia, além de seguir diretrizes de estilo de código definidas pela equipe ou pela comunidade de desenvolvimento.

4. Use exemplos significativos

Incluir exemplos práticos e relevantes na documentação é altamente benéfico. Exemplos claros e bem explicados ajudam a ilustrar como o código deve ser usado, reduzindo a curva de aprendizado para novos desenvolvedores e auxiliando na compreensão de casos de uso específicos.

5. Mantenha a documentação atualizada

A documentação precisa ser tratada como uma parte integrante do código. À medida que o código é modificado ou atualizado, a documentação correspondente deve ser revisada e atualizada para refletir as mudanças feitas. Documentação desatualizada pode levar a confusões e erros.

6. Contextualize e explique decisões

Às vezes, o porquê de algo ter sido implementado de determinada maneira pode não ser imediatamente óbvio. Explicar decisões de design, abordagens técnicas ou soluções escolhidas ajuda a fornecer contexto aos desenvolvedores que interagem com o código, possibilitando uma compreensão mais ampla.

7. Documente de forma automatizada, se possível

Automatizar a geração de documentação sempre que possível pode reduzir a carga manual. Ferramentas como Doxygen, Javadoc ou Sphinx podem ser integradas ao fluxo de trabalho para extrair informações diretamente do código e gerar documentação, simplificando o processo e mantendo-a sempre atualizada.

Como incluir a documentação de código na sua rotina?

Os benefícios tangíveis da documentação de código são vastos. Além de facilitar a manutenção do código, a documentação agiliza o processo de onboarding para novos desenvolvedores, promove a colaboração interdepartamental ao facilitar a compreensão do código e reduz erros decorrentes da falta de clareza. Minha dica, é que você crie um playbook de como criar documentações,  apresente para o seu time, e peça para que os integrantes proponham melhorias contínuas. 

Líderes de tecnologia têm o papel crucial de transformar a documentação em um valor arraigado na cultura de engenharia. Ao destacar a importância da documentação não apenas como uma tarefa, mas como um investimento estratégico, eles incentivam e apoiam a equipe a priorizar a criação de documentação em todas as fases do desenvolvimento.

Na prática, sabemos que muitas das vezes, além das empresas não terem a documentação como parte da cultura, alguns líderes de tecnologia, ainda ficam muito presos em tarefas operacionais para garantir que tudo seja entregue no prazo. Se você se encontra nesta situação, minha recomendação é que você documente as partes mais importantes do projeto, como: Arquitetura geral, organização de arquivos e stack de desenvolvimento. Isso já irá garantir que o seu time tenha um padrão mínimo de trabalho. Com o passar do tempo, reserve horários em sua agenda para ir documentando as partes mais complexas de forma gradativa. 

Projetos bem documentados destacam-se pela clareza e facilidade de compreensão do que está sendo feito, como também pela eficiência na resolução de problemas e pela rápida integração de novos membros na equipe.

‍Seguem abaixo exemplos de documentações simples e objetivas:

API Previsão do Tempo

Problema

Os usuários precisam acessar informações atualizadas sobre a previsão do tempo em diferentes regiões para planejar suas atividades diárias.

Solução

A API de Previsão do Tempo oferece endpoints para fornecer informações meteorológicas precisas e atualizadas para diversas localidades.

Tecnologias Utilizadas

• Linguagem de Programação: Python
• Framework Web: Flask
• Serviço de Previsão do Tempo: OpenWeather API
• Design Pattern: MVC (Model-View-Controller)
  ‍
  ‍

Configuração do Ambiente de Desenvolvimento

Para configurar o ambiente de desenvolvimento local, siga as instruções no arquivo README.md 
‍

Estrutura de Pastas e Arquivos

• app/

• controllers/: Contém os controladores da lógica de negócios.
• models/: Armazena os modelos de dados da aplicação.
• views/: Se necessário, pode conter as visualizações para renderização.
• routes.py: Arquivo de definição de rotas da API.

• config/: Configurações da aplicação.
• tests/: Diretório com testes unitários.
• main.py: Arquivo principal da aplicação.
  ‍

Endpoints

1. Obter Previsão do Tempo por Cidade

Endpoint
GET /api/weather/{city}

Descrição
Retorna a previsão do tempo para uma cidade específica.

Parâmetros
{city} - Nome da cidade desejada.

Requisição
GET /api/weather/London
‍‍

Resposta

{

"cidade": "London",

"temperatura": 12,

"descricao": "Nublado com Possibilidade de Chuva"

}

‍

2. Obter Previsão do Tempo por Coordenadas Geográficas

Endpoint
GET /api/weather/coordinates?lat={latitude}&lon={longitude}

Descrição
Retorna a previsão do tempo com base em coordenadas geográficas.

Parâmetros
{latitude} - Latitude da localização
{longitude} - Longitude da localização.

Request
GET /api/weather/coordinates?lat=51.5074&lon=0.1278

Response
{
"latitude": 40.7128,
"longitude": -74.0060,
"temperatura": 18,
"descricao": "Ensolarado"
}

‍
Exemplo de Uso

‍Para obter a previsão do tempo para uma cidade específica, faça uma requisição GET para /api/weather/{city}. Se preferir utilizar coordenadas geográficas, utilize /api/weather/coordinates?lat={latitude}&lon={longitude}.

Conclusão:

É fato que a documentação é fundamental não só para a saúde técnica do projeto mas também para a saúde organizacional do time de desenvolvimento. Inserir a documentação na cultura do time, encurtando a curva de aprendizado de novos integrantes, é a melhor forma para atingir as metas de longo prazo de qualquer organização que possui um produto baseado em tecnologia. Se você deseja aprender mais sobre como recrutar times que performam e incluir metodologias para facilitar o processo de documentação, alinhado ao Code Review, recomendo o Tech Lead Program do IFTL.

Além de ser um programa direcionado para desenvolvedores que desejam migrar para o cargo de Tech Lead e líderes técnicos que já estão na posição e desejam destravar habilidades essenciais de liderança, o TLP possui uma aula totalmente focada sobre "Metodologias para entrega de software com qualidade". Confira abaixo os tópicos dessa aula:

• Metodologias ágeis

• Code review

• Shape Up

• Como escolher uma metodologia