Bora falar de tédio? DOCUMENTAÇÃO
A documentação é fundamental, mas convenhamos, é uma tarefa tediosa. Uma difinição que eu li aqui pelo Rodrigo Ghiorzi (minha 2D de cabelo azul predileta), é que se você quer ter uma documentação atualizada, basta não ter documentação.
Uma abordagem que pode ser interessante é a documentação Oxygen.
É uma abordagem moderna e eficiente para documentar códigos.
Oxygen está mais para uma filosofia do que para uma ferramenta, ela é criada diretamente no código através de comentários, facilitando para os desenvolvedores documentarem suas funções, classes e lógicas no momento da codificação.
Isso garante que a documentação esteja sempre atualizada com as mudanças do código, promovendo uma maior compreensão e agilidade no desenvolvimento.
Uma dúvida comum é se a Documentação Oxygen fere os princípios do Clean Code, que preza por um código limpo e fácil de ler.
Na realidade, Oxygen pode complementar o Clean Code. Enquanto o Clean Code foca na legibilidade do código, a Documentação Oxygen garante que as intenções, funcionalidades e complexidades específicas estejam claramente expressas, ajudando novos desenvolvedores a entenderem rapidamente o código existente.
Para as empresas, a implementação da Documentação Oxygen significa ter uma base de código mais acessível e fácil de manter, reduzindo os custos de onboarding e treinamento.
Para os times, promove uma melhor colaboração e compreensão do código, especialmente em projetos grandes com múltiplos desenvolvedores.
A Documentação Oxygen pode ser automatizada dentro de um pipeline DevSecOps. Com ferramentas e scripts adequados, é possível extrair e compilar automaticamente a documentação a partir dos comentários no código, integrando-a ao processo de CI/CD.
Desta forma ela pode ser exportada para seu formato de documentação preferido, inclusive ele exporta tudo como HTML se quiser, tornando ela facil de ler e navegar
Isso assegura que a documentação esteja sempre sincronizada com as versões mais recentes do software, fortalecendo a segurança e a eficiência do processo de desenvolvimento.
Por:
