Documentando seus códigos Java

A documentação de programas e projetos é da maior importância para o desenvolvedor e pode ser gerada automaticamente. Veja como.

Por Nenhum

Handerson Ferreira Gomes

Sempre sugiro a todos que estão iniciando na linguagem Java que aprendam e se acostumem a utilizar a documentação da API java. Neste documento as classes Java estão documentadas, com todos seus métodos e interfaces e o que devem fazer, mostrando os tipos de parâmetros e retornos.

O que pouca gente sabe é que esta documentação pode ser gerada, automaticamente, para as classes que você desenvolveu, com sua própria lógica de negócio.

O nome deste utilitário é Javadoc e é fornecido no Kit de Desenvolvimento Java – JDK, desde suas primeiras versões.

É possível abrir o código fonte de uma classe para procurar e compreender todos os métodos desenvolvidos. Porém esta talvez seja uma das piores formas de se aprender sobre uma classe, principalmente quando há uma equipe com vários desenvolvedores, todos gerando suas próprias classes. O processo de ler uma código fonte, procurar por seus métodos e tipos de retorno pode levar um bom tempo, algo que a maioria das equipes de desenvolvimento têm em escassez.

Usando o utilitário javadoc você gera uma documentação altamente acessível e de fácil leitura para todos. Além disso, com o Java 2 novas features foram adicionadas, permitindo que você gere uma documentação mais customizada às suas necessidades.

Como facilitar a vida de sua equipe de desenvolvimento Java

Geralmente quando estamos construindo classes de negócio a colocamos em packages (pacotes) para facilitar a busca e organização das classes. Só para se ter uma idéia, o JDK1.3 é formado por 1840 classes e interfaces divididos em 76 pacotes. Imagine ter todas estas classes em um só pacote – seria a mesma coisa que ter apenas um diretório no computador para todos os nossos arquivos.

Como exemplo estamos criando uma classe chamada Format, que pertence ao pacote com.webinsider.tool . Esta classe foi baseada na dica anterior "Trabalhando com datas em Java" (veja ao lado) e facilita a formatação de datas e números em interfaces Java.

Veja o código fonte da classe Format sem documentação.

Para que os comentários sejam reconhecidos pelo Javadoc é preciso que ele siga uma formatação bastante simples. O comentário sobre a classe em geral aparece no início após a declaração de pacotes, enquanto os comentários sobre os métodos devem ser inseridos antes do início de cada método.

Você pode inserir código HTML nos comentários, como por exemplo colocar em negrito algo que seja importante, gerar uma lista de itens ou inserir um link para outra página de referência. Veja no final do artigo, nas referências, mais detalhes sobre esta formatação.

Veja o código fonte da classe Format com a documentação sobre a finalidade da classe e seus métodos.

Para gerar a documentação simplesmente executamos o comando javadoc no diretório raiz da hierarquia de classes.

Para gerar a documentação da classe Format simplesmente executo: c:javasrc>javadoc –author –version –d api com.webinsider.tool

As diretivas –author serve para considerar as tags de autor, –version informa ao javadoc para considerar as tags de versão e –d aponta para o diretório onde a documentação deve ser gerada. Existem várias outras diretivas que podem ser usadas e elas podem variar dependendo da versão do seu JDK.

Ao final da execução do Javadoc o diretório api conterá alguns arquivos HTML que representam a documentação do pacote com.webinsider.tool.

Clique aqui para ver a documentação gerada pelo javadoc.

Costumo dizer que documentar programas é algo como fazer ginástica ou inglês: todo mundo sabe que é importante, mas a maioria das pessoas deixa em baixa prioridade, para fazer quando tiver mais tempo.

Se já é difícil entender o que muito programador diz, imagina o que ele escreve em código. )

Portanto a documentação de programas e projetos é algo obrigatório a todo desenvolvedor, principalmente para aqueles que trabalham em equipe. Com o Javadoc você pode contribuir em muito para um melhor uso de seus programas e facilitar a vida daqueles que desejam usar suas classes.

Referências:

Este documento tem toda a especificação de como documentar seus programas java para que sejam compreendidos pelo javadoc. [web insider]

1 pessoa comentou o artigo "Documentando seus códigos Java"

Avisos

Os ítens com asterisco ( * ) são campos de preenchimento obrigatório.

Todos os links inseridos nos comentários possuem o atributo rel="nofollow" para impedir com que user agents (como os mecanismos de busca) sigam os links inseridos para desestimular spammers.

Todos devem se identificar através de e-mail válido.

Os e-mails dos usuários não serão divulgados no site.