Viagens, opiniões e afins

Esses dias li um e-mail numa lista de discussão que participo onde a pessoa perguntava como ela deveria fazer para documentar um projeto que ele desenvolveu sozinho. Ainda segundo ele, a ideia é de permitir que num futuro próximo um novo desenvolvedor possa trabalhar no sistema sem traumas e com uma curva de aprendizado rápida.

Antes de tentar responder a pergunta, acredito seja necessário entender a diferença entre análise e documentação.  Muitas pessoas que trabalham com  criação de softwares, acabam confundindo documentar com analisar.  Essa dúvida é normal pois muitas “ferramentas” e “métodos” também se apresentam como opção de documentação, ou o contrário : coisas que deveriam ser usadas para documentar são usadas para fazer análise ( e até acabam com uma má fama sem terem culpa disso – puro mal uso). Um exemplo disso, no meu ponto de vista, é o uml : Muitos usam a UML com o propósito de analisar e modelar. Ela até foi criada com esse intuito pois, quando foi concebida  era bastante custoso codificar e alterar o código feito (lembre-se dos cartões perfurados, cobols da vida, etc) mas hoje isso já não é válido (com linguagens modernas, codificar é rápido e alterá-lo mais ainda). Voltando, UML, no meu ponto de vista, é muito mais documentativa do que modelagem.  Seus diagramas tem um ótimo apelo de representar graficamente um sistema e como diz um ditado: “Uma imagem vale por mil palavras”.

Um outro mito a ser desfeito, insisto, no meu ponto de vista, é de que documentar não agrega valor. Por mais que ninguém diga isso, por mais que ninguém escreva isso, por mais que ninguém assuma isso, muitos de nós considera o ato de documentar como uma atividade secundária, e com isso, delegamos para que outros façam ou, em piores casos, nem o fazemos. A questão que ninguém escreve um sistema para si e, na maioria dos casos, não fazemos isso sozinhos.  Outro ponto é que, possivelmente, não ficaremos para o resto de nossa vidas com aquele projeto, passaremos para outros desafios e aquele sistema deverá ser cuidado por outro pessoa que não necessariamente participou da equipe que o desenvolveu. Tal fato, implica em ter que forma esse pessoa de forma que ela possa dar continuidade ao aplicativo sem comprometer a qualidade dele (estou assumindo que seja aqueles projetos onde temos testes automatizados, linguagens bem expressivas, etc). Logo, tendo todo esse contexto em mente, fica fácil mostrar que documentar, no mínimo, é evitar dores de cabeça futuras.

Mas, enfim, como documentar?

A pergunta poderia ser redigida da seguinte forma para ter mais sentido para nós : Como podemos documentar sem que isso seja uma atividade secundária e agregue mais valor ao sistema? .  A maioria das linguagens modernas oferecem recursos, bastante interessantes, que podem responder essas perguntas. Em Java, nós temos o recurso básico do JavaDoc (comentários em formato especiais que são colocados no código fonte. Depois, através de ferramenta exportamos para um html), em .NET (csharp) temos algo parecido, e por ai segue. Embora isso já seja algo que ajude, considero insuficiente como documentação pois, quem irá ler não terá uma visão do funcionamento ou do comportamento do sistema.

Nesse contexto de comportamento e funcionamento que entram a ajuda primordial dos teste automatizados. Um efeito secundário dos testes automatizados (tanto os teste unitários quando os testes de comportamento) é de, se bem escritos e de grande abrangência,  eles acabam sendo uma boa fonte de consulta para o entendimento da aplicação.  Existe, inclusive, frameworks de teste de comportamento (Behavior Tests) que permitem que se escrevam de forma literal facilitando ainda mais o seu uso como documentação, como por exemplo o Cucumber (Ruby), Pyccuracy ( espero ter escrito certo – Python), etc.

Por fim, eu pessoalmente, acredito que um bom diário de bordo também ajuda bastante. Um diário de bordo, consiste, em algo parecido com um blog ( pode até ser um blog), em que vou escrevendo o dia a dia do desenvolvimento tentando retratar as decisões não técnicas e situações vencidas pela equipe de forma que a pessoa que irá trabalhar com o sistema no futuro tenha também uma visão do por que de certas escolhas, do sentimento da equipe naquele momento, etc.

Em desenvolvimento de sistemas uma das modas, num aspecto mais técnico, é o uso maciço de Padrões de Projeto (Design Patterns).  Chega a ser excessivo, em minha opinião e por isso, seu uso, ao invés de ajudar no projeto, atrapalha e cria verdadeiros monstros (impossíveis de entender, dar manutenção, modificar, compreensão do que está sendo feito difícil, etc). Projetos sem padrões é algo um tanto desordenado, mas projetos com uso exagerado ou de forma “incorreta” torna um sistema um elefante branco.

Por volta de 1995, o GoF (Gang of Four – Erica Gamma, Richard Helm, Ralph johnson, John Vlissides), publicou um livro intitulado : “Design Patterns – Elements of Reusable  Object-Oriented Software”.  Devido a ele, a questão dos padrões de projeto ganhou popularidade e partir de então passou a ser quase que uma obrigação a quem se aventurasse a desenvolver conhecer alguma (as vezes todas) das soluções proposta no trabalho do GoF.  Fiz várias entrevistas nas quais me perguntaram se conhecia Patterns; pediram para explicar e desenhar  algum em particular; e por ai foram.

Padrões não são ruins. Como vários sites e artigos dizem: esses padrões foram soluções de sucesso e testadas ( ou seja, comprovadamente ela funciona e tem um bom desempenho dentro do cenário que ela se propõe) que alguém fez e resolveu catalogar para que no futuro, alguém ao se deparar com um problema de mesma natureza saiba pelo menos um ponto de partida.  De forma bastante simplista, esse catálogo é uma fonte de consulta e onde podemos nos basear, entretanto, não devemos encará-lo como sendo uma verdade absoluta e que não usar o padrão proposto, sem quaisquer alterações,  é um heresia.  Todo o radicalismo independente do lado que penda é ruim. O radicalismo de alguns em dizer que patterns são besteiras e os dos que dizem somente eles devem ser usados não , na minha forma de ver as coisas, o melhor caminho para seguir se desejarmos fazer códigos de qualidade.

Eric Freeman e Elisabeth Freeman em seu livro “Head First Design Patterns ” (Em português o título do livro é : Use a Cabeça Padrões de Projeto), são um ar fresco  e trazem uma nova luz sobre o assunto. Num edição impecável e bem escrita, eles resgatam a questão do uso de padrões do radicalismo e tentam e forma simples mostrar porque devemos pelo menos conhecê-los.  O livro vai direto ao ponto e muitas de suas ideias estão de acordo como vejo o tema.

Um primeiro ponto é que para mim não existe verdade absoluta : um padrão não é e nunca será a única solução para um determinado problema. A diferença está, como já disse antes, que o catalogado é de domínio público (facilita a quem terá que entender o sistema depois), testado e já obteve sucesso em sua aplicação.  De novo, insisto, não é a única opção e pode até, dependendo do caso, não ser a melhor.  Existem diversos fatores a considerar na escolha de um padrão para usar: escopo, custo, tempo, recursos, etc. Como exemplo gosto de citar um caso onde uma pessoa deveria fazer uma aplicação web. Ela teria apenas 4 telas : uma de login, uma para fazer importar uma planilha excel, uma para visualização de dados, etc… O desenvolvedor  acabou, por pura preciosismo usando patterns em quantidades generosas… resultado: tudo ficou um lixo e colocaram a culpa do cara que sugeriu que usassem uma tecnologia de ponta (Struts e Hibernate)

Segundo ponto:  aprender padrões é aprender a se comunicar. Ao aprender os padrões você está adquirindo uma linguagem, de certa forma. Assim, quando quiser explicar a um desenvolvedor do time que poderia fazer de um jeito, sendo ele um pattern, basta que diga : “Fulano vamos usar o pattern XuxaSbrbublesIce++”.Sei que isso pode parecer radical (justo o que critiquei antes) porém se observarmos de um outro angulo a coisa realmente faz sentido

Terceiro : Em alguma parte antes disse que padrões devem ser usados como ponto de partida. O problema está que a maioria das pessoas usa como objetivo. Acredito que muitos serão os casos em que terei que usar uma implementação da forma que o livro ensina, entretanto, haverão tantos outros que terei que adaptar, misturar, usar parte, etc.

Bom agora vai minha opinião:

Conhecer design pattern é bom mesmo que seja para falar mal enquanto toma cerveja com os amigos num #horaextra. Fora isso, ao conhecê-lo você começa a abrir sua cabeça para novas possibilidades e formas de resolver problemas.

Por um motivo que prometo explicar depois, tive que criar uma api para fazer o mapeamento de objeto-relacional para um sistema em Csharp que estamos desenvolvendo.  Como não gosto de reinventar a roda, parti para ver como os frameworks mais usados fazem isso e procurei fazer uma implementação light do que eu vi. Para título de curiosidade me baseiei em Hibernate,  Linq, etc.

O primeiro passo foi determinarmos com o faríamos a questão do mapeamento : para tanto resolvi partir do que hoje é feito pelo hibernate. Dentro do hibernate, simplificando muito o seu funcionamento, você tem um configuração que diz qual campo faz referencia a qual atributo (ou propriedade), qual tabela, as relações, etc.  O hibernate então ao receber o objeto para persistir, por exemplo, pega este dados, monta a query (insert,delete, update, select) e faz a operação. Como disse antes a idéia foi fazer algo light, sendo assim, optamos apenas por mapear os campos, tabela e objetos e não sua relações (com isso eliminamos muita complexidade). Sendo assim, nosso objetos deveriam apenas “saber” qual tabela e colunas a serem mapeadas.

O segundo desafio foi definirmos como iríamos fazer esse mapeamento :  usaríamos um xml, um arquivo de propriedades, base de registro, e por ai seguimos. Após muita discussão vimos que o usuário de nossa api de persistencia seria um outro programador, por isso, teríamos que fazer algo que facilitasse a vida deste cara. Foi aí que decidimos usar Atributos (o mesmo que anotações em Java). Para minha surpresa, criar atributos customizados em Csharp é algo realmente simples (veja o post que escrevi sobre com dicas de como fazer – clique aqui)

Sei que minhas próximas palavras vão soar estranhas para quem não curte codificar como eu, mas :  Não é que a coisa ficou bonita ! A implementação ficou fácil e tudo concentrado na classe sem necessidade de xmls, arquivos externos, problemas de atualização de base de registro, etc.

O meio do caminho – a transformação dos dados dos objetos para relacional e vice versa – foi toda feita com a api de Reflection do .NET. Ela é bastante poderosa, porém com inúmeras diferenças para quem já está acostumado com o Java.  Mas insisto, ela é bem poderosa e interessante.

Ao usar Reflection e rodar nossos testes (isso mesmo estamos desenvolvendo com o TDD – desenvolvimento orientados por teste, escrevemos os testes antes e depois vamos implementando), vimos que ocorria um erro de conversão:  O sistema dizia que não era capaz de converter um valor System.Decimal para System.Int32.

Cabe uma explicação ai: em .NET, ao acessar uma base de dados, para percorres o resultado de uma query você tem um objeto DataReader. Esse objeto é como um mapa dos valores da linha.  Para ele, os valores numéricos ficam mapeados como Decimal e por isso o erro.

A solução achei graças ao Google : basta usar a seguinte linha de código e todos os meus problema sumiram:

O segredo da linha acima é de usar System.Convert.ChangeType . Ele se encarregará de fazer a conversão correta. Como argumento este metodo tem : valor a ser convertido, tipo para qual será convertido o valor.
Bem essa foi a minha aventura das últimas semanas. Achei legal compartilhar pelas dificuldades e de como fizemos para chegar a solução final.

Bom, para o pessoal que tem  Mac e já trabalhou com uma distribuição linux, principalmente com o Ubuntu, deve estar acostumado com a forma simples que é instalar coisas nesses sistemas. Praticamente é abrir um terminal e digitar o comando :

Embora considere o Mac OS um sistema operacional excelente, acredito que o fato de não existe algo nativo como o apt-get é uma das fraquezas dele. Mas, não é por isso que vamos desanimar. Existe um produto similar chamado MAC PORTs, que faz exatamente igual ao apt-get e sua instalação é simples.
Vamos ao passo a passo:

1. Acesse o site do mac ports (www.macports.org) e baixe o pacote de instalação (.dmg)
2. Ao fazer isso o sistema irá começar a instalar. Vá lendo as instruções e fazendo Next, Next até terminar
3. Pronto ele está instalado
4. Para testar abra um terminal e digite o comando : sudo port -d selfupdate

Possivelmente não irá funcionar, pois, você precisa tornar o caminho onde está a instalação visível para o terminal que você usa. Para fazer isso é bem simples:

1. Acesse o terminal
2. Edite os arquivos .bashrc e .bash_profile e acrescente a linha :source ~/.profile
3. Edite o arquivo .profile e coloque as seguintes linhas nele : export PATH=/opt/local/bin:/opt/local/sbin:$PATH

Como os passos acima repita o teste e provavelmente irá funcionar.

Agradecimentos ao Henrique Bastos que ajudou muito com a configuração