views:

18

answers:

2

For consistency, I've always applied comments (in the form of a JavaDoc) to all methods and classes, even if they are simple getters and setters methods or very small wrapper classes. But I'm also striving to write self-documenting code which often makes comments superfluous; i.e. write comments only where needed (and before doing that, try to rewrite the code so you don't need the comment at all). Hence, these two approaches appear to be contradictory to each other.

So should comments which describe a method or class be applied in a consistent manner, or should such comments be written only when meaning is not completely clear from the definition?

+1  A: 

A simple litmus test would be to check if the class has more comments than the code. If yest then it means that your code is too complex and is hard to use for anyone.

So it is best to write self explanatory code. Also there is no need to write comments for things that are obvious like setters and getters.

So I would go with such comments be written only when meaning is not completely clear from the definition.

Faisal Feroz
I accept this as an answer if the code is not an API. If it is, then I would most likely apply the consistant approach instead.
gablin
+1  A: 

I used to create code for every method but now I only create documentation when the remarks add some more information than the code itself.

Here is a question on a similar topic with lots of answers. As the code evolves there is a chance that the update of the documentation is "forgotten". Referring to the question in the link bad documentation is worse than no documentation at all.

rics
I agree that bad documentation is worse than no documentation at all, but what if the documentation is good, but superfluous. Is it still better with no documentation at all?
gablin
I think it depends. If it is really superfluous then it is not needed as it wastes the energy of the developer. Otherwise if the code is written as the part of an API (which means that lots of API users will read the documentation) then it is advisable to write consistent documentation, in other words, for every method of the class.
rics
@rics: Again, I agree. ^^
gablin