Ferramenta para Inclusão do Código de Testes na Documentação das Classes

Transcrição

1 Ferramenta para Inclusão do Código de Testes na Documentação das Classes Herbert Vieira 1, Jolienai Viegas 1, Eduardo Guerra 1, Fábio Silveira 2, Clovis Fernandes 1 1 Instituto Tecnológico de Aeronáutica (ITA), Praça Marechal Eduardo Gomes, 50 Vila das Acácias - CEP São José dos Campos SP, Brazil 2 Universidade Federal de São Paulo (UNIFESP), Rua Talim, 330 CEP São José dos Campos SP, Brazil {hebertvieira,jolienai,guerraem@gmail.com, fsilveira@unifesp.br, clovistf@uol.com.br Abstract. In agile methods for software development, where tests are part of the documentation, it is possible to state that they contains use examplesof that class under test and they are also always synchronized with the implemented logic. However, especially for developers that are not participating directly in the implementation, this is a source where is difficult to find the desired information. This paper proposes a tool to generate class documentation which enables the inclusion of testing code snippets, according to the developer's choice. Resumo. Nos métodos ágeis de desenvolvimento de software, em que os testes fazem parte da documentação, é possível afirmar que eles apresentam exemplos de uso das classes testadas e que estão sempre consistentes com o que está implementado. Porém, principalmente para desenvolvedores de fora do projeto, essa é uma fonte onde é difícil de localizar a informação desejada. Este trabalho propõe uma ferramenta, que ao gerar a documentação da classe, possibilita a inclusão de trechos de código de teste de acordo com a escolha do desenvolvedor. 1. Introdução Uma pesquisa realizada sobre a produção e o uso de documentação durante o processo de desenvolvimento revelou que a documentação gerada tem grande importância no desenvolvimento. Os desenvolvedores preferem a criação e utilização de documentação simples e relevante, tendendo a ignorar documentações complexas e custosas (Nascimento, 2008). A partir desta pesquisa é possível concluir que os desenvolvedores procuram encontrar um caminho para expressar informações em um menor espaço e de forma que permita fácil atualização. Segundo Fowler (2003), as metodologias ágeis são menos concentradas em documentação. Normalmente é criada uma quantidade menor de documentos para uma dada tarefa, concentrando-se em uma maior clareza do código-fonte do programa. Com a criação de testes de unidade, estes acabam sendo utilizados como documentação da classe. A grande vantagem dos testes como documentação em um ambiente ágil é que estão sempre atualizados. Porém, dependendo da complexidade do sistema e da elevada

2 quantidade de cenários de testes que possam vir a existir, muitas vezes pode ser difícil a localização de informações dentro de uma classe de teste. Isso é ainda mais crítico quando o desenvolvedor não faz parte da equipe que criou o componente do qual está sendo buscada a informação. O objetivo do presente trabalho é propor uma ferramenta que faz a inclusão de trechos de código de testes de unidade na documentação da classe testada. Dessa forma, pretende-se criar uma forma de documentação fácil de ser mantida, de fácil navegabilidade e sempre sincronizada com o código fonte. Devido a essas características, ela seria adequada para o uso dentro de uma metodologia ágil. 2. Testes em Ambiente Ágil Segundo Leal (2009), em um ambiente ágil, a criação de testes de unidade é uma prática muito comum. No Test-driven Development (TDD), muito utilizada no desenvolvimento das aplicações nesse contexto, os testes já são criados naturalmente no processo. Essa técnica usa uma abordagem evolutiva na qual o desenvolvedor escreve o teste antes de escrever o código funcional necessário para satisfazer aquele teste (Vieira, 2009). No TDD, desenvolvedores usam testes automatizados para guiar o projeto do sistema durante o desenvolvimento. Os programadores fazem continuamente pequenas decisões aumentando as funcionalidades do software a uma taxa relativamente constante. A cada adição, todos estes casos de teste devem ser executados com sucesso para o novo código ser considerado totalmente implementado. Segundo um estudo comparativo, com a criação dos testes depois da codificação, usando TDD a complexidade do código fonte acaba sendo menor (Canfora et al. 2009). Segundo Mugridge (2003), como conseqüência do uso do TDD, tem-se que o código é escrito de maneira testável isoladamente, pois geralmente, códigos escritos da maneira tradicional, possuem alto acoplamento e uma pobre orientação a objetos. 3. Documentação de Software Em um ambiente ágil de desenvolvimento a documentação deve ser pouca e valiosa. No estudo realizado em Nascimento (2008) sobre a utilização de documentos, apenas 6% dos entrevistados responderam que dispendem muito tempo lendo documentação e 50% que gastam muito tempo com leitura de código fonte. Esses dados ressaltam a importância de uma boa estruturação e clareza do código fonte. Ter um modelo eficiente de documentação tem fundamental importância no processo de desenvolvimento, devido a isso a documentação deve ser simples, eficaz e de fácil entendimento. As próximas subseções exploram mais o papel da documentação no contexto de metodologias ágeis. 3.1 Tipos de Documentação Muitas pessoas acreditam erroneamente que em metodologias ágeis nenhuma documentação é gerada. De acordo com o Agile Manifesto (2001), deve ser dada preferência a se ter software funcionando do que a criar uma documentação detalhada, porém isso não significa que não se deve ter documentação nenhuma, mas que se deve

3 documentar somente o necessário, de forma simples e de fácil manutenção (Ambler, 2006). Basicamente, os tipos de documentos nas metodologias ágeis podem ser classificados em duas categorias distintas: (a) documentação para uso interno no projeto cujo objetivo é a comunicação entre os membros da equipe; e (b) documentação para ser entregue ao final do projeto, a qual faz parte do produto que está sendo entregue para o cliente. O segundo tipo de documento é encarado como parte do produto final e sua confecção deve ser planejada como qualquer funcionalidade do sistema (Poppendieck, 2003). O primeiro tipo citado, quando necessário, deve ser valioso e enxuto para não comprometer a agilidade do processo (Ambler, 2002). 3.2 Documentação Baseada em Comentários da Classe Como alternativa para deixar a informação de documentação próxima ao código fonte, foram criadas ferramentas que geram a documentação do sistema através de comentários realizados no mesmo. Essa abordagem pode ser usada para o compartilhamento de informações dentro da equipe ou quando o produto é um componente cuja documentação da API deve ser entregue. Uma ferramenta bastante utilizada que segue essa abordagem é o Javadoc (Dantas, 2008). A ferramenta JavaDoc foi criado pela empresa Sun Microsystems; ela analisa as declarações e comentários de arquivos fonte e produz um conjunto de páginas HTML, descrevendo as classes, interfaces, construtores, métodos e campos, além de permitir customizações com o uso de Doclet. Segundo Dantas (2008), dessa forma é possível criar com simplicidade e flexibilidade a documentação de programas desenvolvidos nessa linguagem. Os comentários para serem incluídos na documentação devem estar entre as declarações /* e *\. O texto colocado entre estes caracteres são incluídos na documentação gerada. Dentro desses elementos também existe a possibilidade de se utilizar tags como, por explica o significado de cada parâmetro de um método, que documenta o significado do retorno do método. Os comentários na classe e no método são configurados de forma organizada e de fácil visualização. Essa abordagem permite que os desenvolvedores possam navegar facilmente na documentação gerada ou consultar as informações diretamente no código. 3.3 Uso do Teste como Documentação Os testes não são escritos apenas para o computador, e sim, para que futuros desenvolvedores possam entender o funcionamento da classe (Beck, 2000). Nesse contexto o teste atua como sendo uma parte da documentação do sistema. Isso ressalta a importância de se manter a qualidade também no código de testes (Guerra and Fernandes 2007). Os casos de testes, que podem ser utilizados para consulta do comportamento esperado para as classes, ficam definidos em arquivos separados da própria classe. Existem ferramentas que permitem geração de documentação a partir de comentários no próprio código. Os principais problemas enfrentados pelos desenvolvedores em relação a esse modelo de documentação são: As informações de teste ficam distantes das classes devido a estarem em arquivos separados (Hazrati 2009);

4 Os casos de teste não possuem o principal objetivo de documentar e por isso não são facilmente navegáveis e as informações não são facilmente encontradas. Pela documentação da classe, existe a dificuldade no entendimento dos métodos sem exemplos de utilização dos mesmos (Hazrati 2009); Documentação da classe pode ficar desatualizada quando manutenções são realizadas e acabam não sendo documentadas (Hazrati 2009). 4. Ferramenta Proposta A ferramenta proposta chamada JUnitInDoc tem como principal objetivo a inclusão de exemplos de utilização de métodos das classes extraídos da classe de testes de unidade na documentação, gerando uma única fonte de referência mais completa e sincronizada com o código. Ela está definida como uma Doclet, que são programas escritos na linguagem de programação Java que usam a API Doclet para especificar o conteúdo e o formato da saída da ferramenta Javadoc. 4.1 Estrutura da Ferramenta A estrutura de funcionamento de ferramenta está ilustrada na Figura 1 A ferramenta possui um arquivo de configuração onde são configurados os diretórios dos códigos fonte a serem documentados e dos testes de unidade. A partir dessa definição, a ferramenta percorre as classes do programa e as classes de testes de unidade gerando um XML, no formato representado na Figura 2, de cada classe com informações dos métodos e com exemplos de utilização desses. Este XML será formatado por um XSL que irá transformar o documento XML em formato HTML para que o mesmo possa ser exibido em um navegador. O uso de XSL torna possível customizar a exibição das informações, permitindo filtrar somente as informações desejadas pelos profissionais. Fig. 1 Modelo Gráfico do Funcionamento da Ferramenta

5 <?xml version="1.0" encoding="utf-8"?> <classe> <pacote></pacote> <nome></nome> <construtores> <construtor></construtor> </construtores> <metodos> <metodo> <nome></nome> <obs></obs> <parametros> <param> <var></var> <tipo></tipo> </param> </parametros> <retorno> <tipo></tipo> <obs></obs> </retorno> <codigo_exemplo></codigo_exemplo> </metodo> </metodos> </classe> 4.2 Exemplo de Utilização Fig.2 Estrutura do Documento XML gerado pela ferramenta Para exemplificar o funcionamento da ferramenta, será utilizada a classe Baskara, cujo código está apresentado na Fig.3, que realiza o cálculo das raízes de uma equação do segundo grau. Ela possui um construtor onde são passados os valores de A, B e C e dois métodos, sendo um chamado de CalculaBaskara(), responsável por calcular os valores dos atributos X1 e X2, e outro chamado CalculaDelta(), responsável por calcular e atribuir o valor no atributo delta da classe. public class Baskara { public double X1; public double X2; public double Delta; public final double a, b, c; public Baskara(double a, double b, double c) { this.a = a; this.b = b; this.c = c; /** * O método realiza o calculo e seta os valores de X1 e X2 */ public void calculabaskara() Delta = calculadelta(); X1 = (-b + Math.sqrt(Delta)) / (2 * a); X2 = (-b - Math.sqrt(Delta)) / (2 * a); /** o valor de delta */ public double calculadelta(){ double d = 0; d = ((b * b) - (4 * a * c)); return d; Fig. 3 Classe Baskara

6 Os métodos da classe Baskara serão utilizados para exemplificar a inserção do código de teste na documentação. Para que isso seja possível, é preciso adicionar no código do teste de unidade, as que irão determinar o início e o fim respectivamente do código a ser inserido na documentação do método da classe. A Fig. 4 mostra a utilização das anotações nos teste de unidade da classe. O nome do método de teste deve seguir um padrão de nomenclatura para que a ferramenta consiga associar o teste de unidade com o método da classe. O padrão adotado foi [test] + [nome do método da classe] + [número seqüencial do teste]. Esse padrão foi adotado para diminuir o número de configurações necessárias, porém outras soluções, como o uso de anotações e configurações no doclet, estão sendo consideradas em versões futuras para não amarrarem o nome dos casos de teste. public class testequacao2grau extends TestCase { public void testcalculabaskara1(){ //@JdocBegin double a=4, b=-8, c=0, valorx1=0, valorx2=0; Baskara calc1 = new Baskara(a, b,c); calc1.calculabaskara(); valorx1 = calc1.x1; valorx2 = calc1.x2; //@JdocEnd double resultx1 = 2.0; double resultx2 = 0.0; assertequals(valorx1, resultx1); assertequals(valorx2, resultx2); public void testcalculadelta1(){ //@JdocBegin double a=4, b=-8, c=0, delta=0; Baskara calc1 = new Baskara(a, b,c); delta = calc1.calculadelta(); //@JdocEnd double resultdelta = 64.0; assertequals(delta, resultdelta); Fig.4 Teste de unidade com Junit Para gerar a documentação, basta executar o Javadoc configurando a Doclet da ferramenta proposta. A Fig.5 mostra o trecho da documentação gerada pela ferramenta com os dois métodos da classe Baskara. Pode-se observar que nos métodos foram inseridos os trechos do código dos testes de unidade respectivos. A principal vantagem da utilização da ferramenta proposta, que pode ser claramente percebida, é que ela gera uma única documentação com as informações da classe juntamente com o código de exemplo de sua utilização extraído do teste de unidade. Dessa forma, a cada nova interação a documentação do projeto estará sincronizada com o código. Outro fator a ser ressaltado é o pequeno esforço que deve ser empregado para a criação da documentação, tornando-a adequada para uso em conjunto com metodologias ágeis. Vale ressaltar que a ferramenta apresentada ainda se encontra em fase de desenvolvimento e que ainda não está finalizada para ser utilizada em ambiente de produção. Outras opções serão adicionadas na ferramenta visando torná-la mais flexível

7 e para simplificar o seu uso, além do teste da mesma em um ambiente real. Porém, os resultados obtidos até o momento são suficientes para ilustrar como a abordagem pode ser empregada para a geração de uma documentação de fácil manutenção e que não consome muito esforço da equipe de desenvolvimento. 5. Conclusão Fig.5- Trecho do Documento gerado Uma das propostas das metodologias ágeis é focar o esforço da equipe no produto final ao invés de na geração de documentação. Para dar segurança que esse código gerado atente seus objetivos e que refatorações não irão alterar comportamentos indevidamente, são utilizados testes de unidade, que muitas vezes são criados antes do próprio código através do TDD. Como os casos de teste criados acabam apresentando exemplos de como utilizar as classes em variados cenários e estão sempre em sincronia com o que está implementado, muitas vezes eles acabam sendo utilizados também como documentação da classe. Uma desvantagem dessa abordagem, é que devido ao número de casos de teste e sua separação das classes de produção, muitas vezes a informação procurada é difícil de ser localizada. Dentro desse contexto, o presente trabalho apresenta a proposta de uma ferramenta para geração de documentação que inclui trechos de casos de teste como exemplos de uso da classe de produção. A abordagem apresentada gera um esforço adicional muito pequeno por parte do desenvolvedor, o qual precisa apenas marcar os trechos de código que precisam ser incluídos. Dessa forma, quando um teste for modificado, essa mudança será refletida diretamente na documentação, gerando um pequeno esforço também para a manutenção da documentação. Pelos motivos

8 apresentados, chega-se a conclusão que a ferramenta é adequada para o uso em um ambiente ágil. Devido à ferramenta ainda estar em desenvolvimento, um trabalho futuro imediato é a geração de uma versão de produção da mesma. Com a implementação concluída, ela será utilizada em um projeto para validar o seu uso dentro de um ambiente real. 6. Bibliografia AGILE MANIFESTO, Manifesto for Agile Software Development, Disponível em < Acesso em: 10/03/2010. AMBLER, S. W. (2002) Agile Modeling: Effective Practices for extreme Programming and the Unified Process. Wiley, AMBLER, S. W. (2006) Examining the Agile Manifesto. Disponível em < Acesso em 08/04/2010 BECK, K. (2000) Extreme Programming: Explained, 1ª Ed. Boston: Addison Wesley. CANFORA, G.; VISEGGIO, C.; GARCIA, F.; PIATTINI, M. Measuring the impact of testing on codtructure in Test Driven Development. Tenth International Conference on Agile Processes and extreme Programming in Software Engineering (XP 2009), DANTAS, C. F. F. (2008) Javadoc. Universidade do Estado do Rio Grande do Norte. Mossoró. FOWLER, M. (2003). The New Methodology. Disponível em < Acesso em 15/03/2010. GUERRA, E.; FERANANDES, C. Refactoring Test Code Safely. In: ICSEA, 2007, Tahiti. ICSEA'07, HAZRATI, V. (2009) Two Types of Agile Documents - No More, No Less!. Disponível em: < Acesso em 14/03/2010 LEAL, I. G. (2009) Requisitos de Metodologias de Teste de Software para Processos Ágeis. Universidade Federal de Minas Gerais, Belo Horizonte. MUGRIDGE, R. (2003) Test Driven Development and the Scientific Method. University of Auckuland, New Zealand. Agile Development Conference, NASCIMENTO, G. V. (2008) Um Modelo de Referência para o Desenvolvimento Ágil de Software. Dissertação. (Conclusão de Mestrado) Universidade de São Paulo, São Paulo. POPPENDIECK, M.; POPPENDIECK, T. (2003) Lean Software Development: An Agile Toolkit. 3º Ed. New York. Addison-Wesley. SASSE, E. (2005). Test Driven-Development. Disponível em: < Acesso em: 29/03/2010. VIEIRA, R. M. (2009) Desenvolvimento de software embarcado utilizando a metodologia ágil FDD Desenvolvimento guiado por funcionalidades. Instituto Tecnológico de Aeronáutica. São José dos Campos.