Documentação e Best Practices: Um caso de uso

Documentação, a palavra mais assustadora e antipática criada dentro do ambiente de desenvolvimento.

Ok, isso pode ser o que pensamos, mas não é a verdade. Documentação é uma parte fundamental do desenvolvimento de qualquer sistema, seja ele em equipe ou não. Quantas vezes você não se deparou com um código que voce mesmo escreveu algum tempo atrás e simplesmente ficou sem entender absolutamente nada do que havia feito? Acredite, acontece.

Em um ambiente de desenvolvimento em equipe a situação fica ainda pior. Cada programador tem sua assinatura, desafie varias pessoas a escrever um código para resolver um determinado problema e verifique o resultado. Cada um vai escrever o código de uma forma, então imagine a confusão na hora de se dar manutenção no código de outra pessoa.

A documentação esta ai justamente para preencher esta lacuna, atitudes simples, como uma linha de comentário descrevendo o que o bloco de código logo abaixo, fazem uma grande diferença para o entendimento. Além disso temos a documentação completa de classes e códigos, que pode ser baseado no phpDoc , por exemplo.

Recentemente estive projetando um sistema que será implementado por uma equipe de três pessoas, e pra piorar, eu como gerente de desenvolvimento vou passar quinze dias fora, sem contato com a equipe. Eu precisava achar uma forma de deixar meu parceiro “em código” programar livre, tocar o projeto junto com o designer, mas sem gerar códigos que entrem em conflito com o resto do sistema, ah sim, este sistema integrará 5 subsistemas em uma base única de intranet, mas acho que estes detalhes são coisas para outro post.

Após projetar o sistema e definir objetos e outros detalhes gerais do próprio sistema, tirei meu tempo e aproveitei o recesso do resto da equipe para escrever o “Manual de Best Practices” do sistema. Para que tudo corra bem é necessário definir um padrão para que todos envolvidos possam seguir este padrão e então produzir código inteligivel e que se “conecte”.

O manual explica detalhadamente toda estrutura do sistema, desde a estrutura física até as normas de documentação. Começo descrevendo a estrutura do sistema e a integração dos sub-sistemas, explicando a estrutura de pastas e ditando as normas de nomenclatura de arquivos. Em seguida passamos pelo desenvolvimento de módulos, tratamento de erros, conexão com o banco e apresentação. Finalmente apresento as diretrizes de documentação para que possamos das continuidade ao que foi feito.

A apostila como um todo terá mais de 9 capítulos e cerca de 30-40 páginas (ao escrever isso ainda não finalizei a apostila), mas deve continuar sendo re-escrita e novas instruções e padrões devem ser adicionadas. O nível de detalhamento deve melhorar, e alguns padrões de formatação de código devem ser incorporadas.

Funciona? Bem eu acredito que teremos muitos menos problemas de incompatibilidade, mas com certeza voltarei para relatar meu caso de sucesso (ou insucesso) e incrementar na definição e dicas de documentação.