Should you document everything or just most?
- by TheLQ
It seems a bit of a controversial subject to document everything, including the "JavaBean" syntax of getters and setters for fields: People say its needlessly long and repetitive breaking DRY (don't repeat yourself), that the naming convention should explain everything, and it clutters code/documentation. Sometimes those arguments work. But other times, you end up with this:
Above is common to open source projects that do boldly follow those principles. Your left with entirely useless documentation. That doesn't explain anything about whats going on underneath, the possible effects, or even what the expected value is (could it be null or never null? I don't know, the Javadoc doesn't tell me).
So when should I document? Do I document everything even if it occasionally clutters code? Or do I document nothing since in my eyes its "obvious"?
