Dicas de Documentação
Autor: Felipe Ramos | Publicado: 2011-11-24T18:35:00-08:00

Um dia desses um usuário de um sistema que estou desenvolvendo no meu trabalho quis tirar uma dúvida comigo sobre o sistema. Em um módulo de controle de viagens dos funcionários de uma empresa, após a aprovação da viagem pelo responsável pela área do funcionário, o sistema envia emails sinalizando a aprovação. O usuário queria saber se caso ocorresse uma reprovação da viagem, o sistema enviaria algum email, e quais seriam as pessoas que receberiam o email. Como não fui eu quem desnevolvi este módulo, eu chamei ele do meu lado e abri o fluxo que fazia este controle de aprovação. Fui seguindo passo-a-passo o processo do fluxo e consegui mostrar pra ele o que ele queria saber (e a mim também, que não conhecia em detalhes o módulo do sistema, já que não participei do desenvolvimento desta parte), tudo isso sem precisar abrir um processamento do fluxo. Sabe por quê? Devido à boa documentação do fluxograma feita pela desenvolvedora do módulo. O usuário teve a resposta de forma rápida e muito simples (além de ficar impressionado pela forma simples como eu desenvolvo o sistema que ele usa, hehehehe) e eu não precisei perder tempo tentando adivinhar o que o fluxo fazia.Usei este exemplo real do dia-a-dia de um desenvolvedor de sistemas para tocar em um assunto muito interessante para nós desenvolvedores: a boa e velha documentação do código-fonte. Eu conheço muitos sistemas feitos com o Maker e também muitos desenvolvedores que trabalham com a ferramenta e me surpreende que uma parcela considerável não presta muita atenção na documentação e organização dos fluxos. Isso é um erro gravíssimo. Na versão 2.5 existia um recurso de documentação automática dos objetos do fluxo, ele montava um texto básico tomando por base as funções usadas no objeto e seus parâmetros. Aquilo era horrível! Ainda bem que foi removido das versões posteriores. Já vi no Gumaker muita gente reclamando da falta deste recurso, mas foi ótimo ele ter sido removido, pra mim ele fugia um pouco das características do Maker. Um desenvolvedor preguiçoso simplesmente ativava esta opção e achava que seu fluxo estava documentado, mas não estava. O objetivo daquela documentação automática do objeto era facilitar, o desenvolvedor deveria editar o texto que foi criado, deixando-o mais completo. Mas ninguém fazia isso. Sabe quando eu usei este recurso? Nunca. Sempre digitei manualmente objeto por objeto a documentação dos meus fluxos.O sistema deixa de funcionar por causa da documentação? Não. Mas ela é parte essencial do processo de desenvolvimento de qualquer sistema, independente da tecnologia usada. Mas com o Maker ela tem papel ainda mais importante. Sem ela uma grande vantagem do uso de fluxogramas é perdida, que é a facilidade de entendimento das regras de negócio. Imagina dar manutenção em um sistema que você não fez, e quando abre um fluxograma as caixas estão todas vazias. Ou com aquela documentação básica somente para não deixar o fluxo em branco. Por exemplo:Uma boa documentação de um fluxo no Maker é aquela que você consegue entender o que foi feito sem precisar abrir o objeto para olhar o que tem dentro. Seu fluxo abre uma consulta em uma tabela? Não escreva simplesmente "Abrir Consulta". Detalhe o processo, diga em qual tabela está sendo feita a consulta, qual o filtro usado nela. O texto ficou grande? Não importa, aumente o tamanho do processamento para caber o texto (não precisa exagerar, não escreva uma redação de vestibular na descrição do objeto, seja completo e direto). Daqui a alguns dias, meses ou anos em que você voltar a mexer no fluxograma o entendimento será muito mais fácil. Se você trabalha em equipe então, nem se fala.Lembre-se: o fluxograma não está ali apenas para você "programar". Ele é muito mais que isso. Ele é o seu diferencial com o Maker. Ele é a aproximação do desenvolvedor com o cliente, com o usuário final. Ele é a documentação do seu software que será entregue ao seu cliente. Já teve a experiência de entregar a um cliente uma documentação de um sistema gerada pela documentação automática do Maker, com os fluxos todos bem limpos, organizados, com uma documentação satisfatória? Pense nisso quando for desenvolver um fluxograma a partir de agora.Eu acho este é um assunto bastante interessante e creio que posso ajudar ao menos um pouco os desenvolvedores Maker dando algumas dicas de documentação de objetos de fluxogramas, variáveis, formulários. Irei escrever novos posts abordando este assunto e estarei publicando no blog em breve.