Documentação de código com o Doxygen
Uma coisa que eu tenho observado ao longo do tempo em que venho trabalhando, tanto em hardware quanto em software, é que em geral o nível de documentação é bem precário.
Talvez seja o fato de que os prazos sempre são bem apertados e os desenvolvedores preferem se preocupar em fazer o produto funcionar acima de qualquer coisa. O problema é que depois de algum tempo quando alguém retomar o trabalho para fazer manutenções ou extensões vai ter sérias dificuldades para levar o trabalho adiante.
Tanto engenheiros quanto o pessoal de informática não costumam documentar adequadamente seus produtos, mas quando se trata de software parece que os engenheiros são mais relapsos que os cientistas da computação. Talvez porque na formação básica de engenharia não existam disciplinas relacionadas à engenharia de software ou à metodologias de desenvolvimento.
Além disso, como no mundo da engenharia às vezes o nível de programação é um pouco mais embaixo (e.g. microcontroladores), então os engenheiros acabam tendo dificuldade em documentar os programas (e muitas vezes o próprio hardware - o camarada faz o rascunho numa folha A4 e não passa o esquemático a limpo em um programa EDA, tipo Protel, Eagle, etc).
Uma boa notícia é que existem ferramentas que ajudam, e muito, na documentação do código. Uma que eu recomento é o Doxygen.
O Doxygen é capaz de gerar documentação em HTML, Latex e mais um monte de formatos. Além disso, a documentação é bem interativa, sendo que ele faz grafos com dependência entre módulos, referência cruzada, listas de bugs, etc. É muito fácil de usar e em sua homepage existe um manual completinho (que por sinal foi feito com o Doxygen). Em alguns minutos o esqueleto da documentação já está pronto.
Pra quem escreve algumas centenas (ou milhares de linhas de código) é simplesmente essencial.
Talvez seja o fato de que os prazos sempre são bem apertados e os desenvolvedores preferem se preocupar em fazer o produto funcionar acima de qualquer coisa. O problema é que depois de algum tempo quando alguém retomar o trabalho para fazer manutenções ou extensões vai ter sérias dificuldades para levar o trabalho adiante.
Tanto engenheiros quanto o pessoal de informática não costumam documentar adequadamente seus produtos, mas quando se trata de software parece que os engenheiros são mais relapsos que os cientistas da computação. Talvez porque na formação básica de engenharia não existam disciplinas relacionadas à engenharia de software ou à metodologias de desenvolvimento.
Além disso, como no mundo da engenharia às vezes o nível de programação é um pouco mais embaixo (e.g. microcontroladores), então os engenheiros acabam tendo dificuldade em documentar os programas (e muitas vezes o próprio hardware - o camarada faz o rascunho numa folha A4 e não passa o esquemático a limpo em um programa EDA, tipo Protel, Eagle, etc).
Uma boa notícia é que existem ferramentas que ajudam, e muito, na documentação do código. Uma que eu recomento é o Doxygen.
O Doxygen é capaz de gerar documentação em HTML, Latex e mais um monte de formatos. Além disso, a documentação é bem interativa, sendo que ele faz grafos com dependência entre módulos, referência cruzada, listas de bugs, etc. É muito fácil de usar e em sua homepage existe um manual completinho (que por sinal foi feito com o Doxygen). Em alguns minutos o esqueleto da documentação já está pronto.
Pra quem escreve algumas centenas (ou milhares de linhas de código) é simplesmente essencial.
Comentários