For consistency, I've always applied comments (in the form of a Jav开发者_运维问答aDoc) 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?
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.
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.
精彩评论