JavaDoc: Dry for comments, or do not comment every method... 📎
Sample:
/**
* This method sets a password [redundant information]
* @param pwd - a password [also redundant...]
*/
public void setPwd(String pwd){
this.pwd = pwd;
}
In my opinion is the javadoc comment only redundant information and should be removed. It would be better in this case not to comment. Also default-constructors,
obvious methods like initialize etc. shouldn't be commented because of maintainability. Commenting obvious, fine grained, stuff is evil. Reasons:
- You need time to describe obvious stuff.
- The amount of documentation will grow, so it is harder to understand the system -> the maintainability suffers...
- You have to keep your comment in-sync with your code
From my perspective it is much better to comment the intension - the backgrounds and not so obvious reasons. So don't repease yourself - be DRY...
So what should be commented:
- The responsibility of every class (a must), and optional of methods
- Packages have to be documented (interesting enough - the QA department was not interested in package comments...). Especially the reponsibilities of the package, which cohesive elements are grouped here, is it a component, subsystem or even application, etc.
- Additional non-functional "meta" stuff like parameter ranges, null/not null, Quality of Service (for SOA) etc. For this purpose custom JavaDoc tags or JSR-175 with APT (for JavaDoc-generation) can be used.
I described more general (even Java-independent) aspects of architecture documentation in my (caution: german) book "Enterprise Architekturen".