Estou fazendo um programa MVC, porém na hora de descrever em um javadoc
o que cada janela faz, eu fiquei em dúvida entre colocar esses comentários nas próprias forms
(Model), ou nos controllers
das respectivas janelas. Qual seria o mais correto ? Pois a form
é a essência da janela, e o controller
é quem faz a maioria das coisas ... Me ajudem !
Devemos dar pelo menos uma breve descrição de ambos, para que o programador que vá pegar os mesmos não tenha nem a possibilidade de não entender do que se trata.
/**
* Modelo para criação e validação do Código de Barras da Caixa
*
* @author João Victor B. Magalhães
* @since 0.1
* @version 0.1
*
*/
public class CodigoDeBarrasCaixa implements CodigoDeBarrasBoleto {
private String digitos;
private BoletoBancario boleto;
private static final int TIPO_DE_COBRANCA = 2;
private static final int ID_EMISSOR_BOLETO = 4;
private static final int TIPO_MOEDA = 9;
}
Não vejo necessidade em documentar os Getters e Setters, mas caso tenha algum método mais complexo ou um atributo de difícil entendimento é bom que documente também. No controlador a mesma coisa, dê uma descrição do que ele faz e caso ele tenha algum método fora do "comum" documente-o. Se já for um programa que está distribuído em uma equipe coloque sempre o @since para a equipe saber quando você adicionou o método e o @version também.
O javadoc não é a ferramenta mais indicada para descrever como utilizar a interface gráfica da aplicação, se é isso que você está tentando fazer. Ele serve para você descrever como utilizar as classes (e os métodos, consequentemente) do seu projeto.
No caso, se o que pretende fazer for realmente documentar as classes, você deve fazer isso tanto na model quanto na controller.
-
Qual seria a melhor forma de descrever a função de determinada classe e/ou método ? Os próprios comentários "normais" mesmo ? – Daniel Santos 3/06/16 às 0:27
-
1@DanielSantos não não, no que se refere a classes e/ou métodos (que serão utilizados por outros desenvolvedores, ou mesmo você no futuro) é que você deve usar o javadoc. O que eu mencionei foi que se a ideia fosse documentar a utilização da interface gráfica por parte dos usuários aí sim o javadoc não seria o mais indicado. – Gabriel Rossini Martins 3/06/16 às 0:33