Documentação de software – Vilã ou mocinha?

É quase certo que em algum momento da sua vida você se deparou com um trecho de código complexo e não conseguiu compreender o que ele fazia. É comum que isso ocorra quando se está analisando o código escrito por outro programador, mas é bem possível que isso aconteça também com um código que você tenha escrito a algum tempo atrás. Agora deixe-me adivinhar: É muito provável também que este trecho de código não tenha nenhum comentário ou que os comentários existentes não o ajudem em nada a entender o que o algoritmo faz, certo? É muito provável também que não haja outra fonte de informação a respeito do algoritmo além dos míseros comentários no fonte. Talvez neste momento você esteja pensando: Na mosca!

O fato retratado acima é apenas uns dos problemas comuns de documentação enfrentados no desenvolvimento de software. As desculpas para não documentar adequadamente são muitas: falta de tempo, falta de colaboradores para a atividade, custos adicionais, requisitos instáveis, etc. Seja qual for o pretexto escolhido, o mesmo não justifica os riscos que decorrem de tal conduta em um projeto.

Neste artigo iremos tratar da importância da adequada documentação do software, como ela deve ser feita e quais são os seus benefícios diretos e indiretos. Veremos também como é possível documentar sem comprometer os prazos do projeto usando-se apenas de bom senso e como a qualidade do produto de software está intimamente ligada a documentação oferecida para o mesmo.