adam bien's blog

JavaDoc: Dry for comments, or do not comment every method... 📎

In one of my last project the QA-department ask me to comment Getters/Setters because of metrics. I refused this strictly, because in my opinion some methods cannot be well commented.
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:
  1. You need time to describe obvious stuff.
  2. The amount of documentation will grow, so it is harder to understand the system -> the maintainability suffers...
  3. 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:
  1. The responsibility of every class (a must), and optional of methods
  2. 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.
  3. 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".