1

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?

gablin
  • 4,678
  • 6
  • 33
  • 47

2 Answers2

1

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
  • 12,458
  • 4
  • 40
  • 51
  • 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 Sep 21 '10 at 11:28
1

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.

Community
  • 1
  • 1
rics
  • 5,494
  • 5
  • 33
  • 42
  • 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 Sep 18 '10 at 20:16
  • 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 Sep 19 '10 at 12:48
  • Even documentation which is flawless and aids in discerning what changes may need to be made to some code, will add to the effort required to actually make such changes, since the documentation will have to be updated to match the code. If the time saved determining what to fix outweighs the extra cost of maintaining the documentation, then the documentation is a help. If not, it may be a hindrance. While I haven't read it formalized, I think there should be a distinction between data types and methods which exist to fulfill a specialized need, such that... – supercat Jan 20 '13 at 22:15
  • ...one shouldn't really try to understand it outside the context where it was used, versus those which are designed to be more generally useful. This distinction may cross private/public boundaries, especially when applied to data types. If a public method which may be invoked across threads needs to return three values to the caller, I'd suggest that it's better to define a minimal struct for that purpose, with no real spec beyond "three fields, with names/types (whatever), that hold whatever the caller puts there", and then have the method returning the struct describe what it puts there. – supercat Jan 20 '13 at 22:31