Documentar classes e metodos

Assuntos Gerais
#1

Bom dia.
Eu, assim como a maioria dos desenvolvedores que conheço, possuo uma certa dificuldade em escrever uma documentação relevante das classes e metodos que produzo.
Qual conteúdo que vocês acham relevantes de serem inseridos nos comentários de classes e métodos?
Vocês acham realmente necessário inserir comentários em todos os métodos, inclusive getters e setters que são óbvios? Por exemplo getNome(), getCPF(), etc.

Alguém tem uma “formula” para criar uma documentação interessante?

No site da MSDN, foi publicado um artigo interessante sobre documentação de API, os exemplos estão em C#, porém o que interessa realmente é o conteúdo dos comentários e não a sintaxe. Segue o link: http://msdn.microsoft.com/pt-br/magazine/gg309172.aspx

Abaixo criei uma classe simples e gostaria de ver com vocês fariam os comentários de métodos e classe para gerar uma boa documentação.

public class Matematica {

	public int somar(int x, int y){
		return x+y;
	}
	
	public int subtrair(int x, int y){
		return x-y;
	}
	
	public int multiplicar(int x, int y){
		return x * y;
	}
	
}

Obrigado.

#2

Você pode documentar todos os métodos usando o javadoc.
Veja o link:
http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html

Com um simples comentário cada método, você teoricamente terá uma documentação rica e não perderá tanto tempo lembrando dos métodos
e comentando.

É uma prática que eu as vezes utilizo a dar certo.

#3

Cara…documentar métodos é “fundamento”. A parte de encapsulamento, ou os chamados getters e setters são desnecessários de comentário até o momento em que você não precise acrescentar nenhum comportamento adicional ao método. Os demais métodos são necessários de documentação sim. Comentários são “desejáveis”, mas JavaDoc…na minha humilde opinião é fundamento.
É como mandar um currículo meu para uma empresa. Se não declarar aquilo que faço ou que pretendo fazer…não tem como o entrevistador me analisar com clareza. Muitas vezes deduzindo o que faço ou pretendo fazer, mas nunca tendo certeza. Mesma coisa as classes e métodos. Se eu criei…saberei (até um determinado tempo) do que se trata. Se não criei…terei de analisar, testar e até deduzir do que se trata.

#4

Isso é mais uma questão de bom senso…

por exemplo, se eu disser-lhe um nome de método e o tipo de retorno você saberá exatamente o que o método faz (não interessa COMO o método faz, mas O QUE o método faz), por ex, um método validaCPF(String cpf):boolean é bastante intuitivo, mas como alguém pode ter absoluta certeza se ele vai retornar true ou false quando o cpf for válido? Resposta --> documentação!!

Agora um exemplo de método que talvez não seria tão necessário ser documentado (apesar de ser altamente recomendável documentar todos eles) seria um método isValid():boolean de uma classe CPF. Agora qualquer um pode afirmar com uma margem grande de certeza que o método irá retornar true se o cpf representado pelo objeto for válido e false caso contrário…

Minha linha de raciocínio é mais ou menos essa aí…

Por outro lado, Construir uma documentação do programa a partir do javadoc (ele cria uma arvore de documentos html com a documentação, a partir dos comentários de bloco (/** */ ) antes das classes e métodos, lista de métodos, etc… ) também é interessante, visto que isso facilita muito a manutenção futura, por pessoas que não participaram do desenvolvimento… (concordando com o cara aqui de cima, javaDoc não é estritamente necessário)

Resumindo: coloque nos comentários o que o método faz (caso o nome do método + tipo de retorno não explicite isso) … getters e setters só necessitam de documentação mesmo caso haja algum código de validação…

#5

Agora, respondendo sua pergunta, eu faria a documentação desses métodos assim:

public class Matematica {

        /** Retorna o resultado de x + y */
	public int somar(int x, int y){
		return x+y;
	}
	
        /** Retorna o resultado de x - y*/
	public int subtrair(int x, int y){
		return x-y;
	}
	
        /** Retorna o resultado de x * y*/
	public int multiplicar(int x, int y){
		return x * y;
	}
	
}
#6 
public class Matematica {  
  
    public int somar(int x, int y){  
        return x+y;  
    }  
      
    public int subtrair(int x, int y){  
        return x-y;  
    }  
      
    public int multiplicar(int x, int y){  
        return x * y;  
    }  
      
}

Eu não comentaria esse código. Está mais do que claro o que ele faz, sendo assim, não há necessidade alguma de comentá-lo. Geralmente, comentários são um sinal de código mal feito. Se os nomes de suas variáveis e métodos são significativos, se cada método e classe cumpre com uma função e tem uma responsabilidade, e são escritos de maneira clara, sem abreviações, etc., comentário são minimamente necessários. Claro que as exceções existem, e nestes casos eles devem ser usados.

#7