Documentação de software emergente

Devido ao meu trabalho na área de consultoria eu tenho a oportunidade de conversar diariamente com empresas desenvolvedoras de software em todo o Brasil ou empresas que tenham algum tipo de desenvolvimento interno de software e a frase documentação sempre é citada pelos clientes no meio das conversas.

Ao longo dos anos passaram a vender no mercado o tal conceito das fábricas de software e seus trilhões de processos que seriam a bala de prata para todos os projetos de desenvolvimento de software. Na prática o que observamos é que esse conceito foi sendo repassado e outras empresas começaram a entender o mesmo também como solução esquecendo completamente do maior bem da empresa que é o código fonte. É um fato real. Não adianta ter um grande livro explicando o que “seria” o código fonte se quando chega o momento da manutenção não será utilizado uma vez que o código reflete outra realidade.

Por isso quando pensar em um projeto valorize o principal ativo que é o código fonte desenvolvendo o mesmo de forma clara e autoexplicativa incluindo um padrão de desenvolvimento que seja entendido por todos na empresa e use nomes claros que por si só já indicam o que é aquela funcionalidade. Utilizem os recursos de comentários disponíveis para complementar caso julgue necessário.

O uso de testes automatizados de software também compreende a sua documentação, pois representam como a funcionalidade tem que realmente funcionar. É o conceito de ter a documentação viva interagindo com o projeto em tempo real.

No Visual Studio 2010 você tem a disposição um conjunto grande de diagramas vivos que representam suas classes, camadas e até permitem uma ampla investigação de sua arquitetura de software. Produzir um código padronizado, fácil de manter e com testes unitários garantirá além da rápida compreensão do mesmo uma manutenção segura que é o que traz mais valor para o negócio. É muito caro manter um software. Essa conta só chega depois.

Aplicando uma simples regra de Code Analysis você pode padronizar os nomes dos métodos, variáveis, classes usando o modelo ‘Microsoft Names’ que já é o mesmo utilizado no .NET Framework. Em conjunto ao teste unitário você pode usar o Code Metrics para avaliar a complexidade na manutenção desse código identificando códigos complexos que podem passar por um refactoring agrupando códigos similares e diminuindo o tamanho dos métodos.

Com uma simples arquitetura definida você pode montar um diagrama de arquitetura e integrar a validação do mesmo no servidor de Build garantindo que todos utilizem as camadas conforme o padrão estabelecido que é do conhecimento geral.

Outro grande aliado é o teste unitário (Unit Test) que aplicado em conjunto com a cobertura de código (Code Coverage) usando técnicas como TDD (Test Driven Development) vão contribuir para a construção de um código que realmente atende o valor de negócio proposto e já nasce com a sua documentação pronta no formato que o desenvolvedor entende.

Portanto antes de pensar em escrever algo responda sempre a pergunta “Que tipo de problema me resolve?”

Sucesso nos projetos e até a próxima! Participe nos comentários.

[],
Ramon Durães
MVP, Visual Studio ALM
Especialista em desenvolvimento de software