One of the major reason I love programming in Java, is the excellent quality of the documentation. I can look up any class, method, field, enum, annotation, or even an entire package and get loads of great documentation on the subject. It doesn’t just tell me what it does, it also tells me valid inputs, outputs, what exceptions can be thrown, and often even the process the code goes through.
I’ve heard many people tell me: just look at the code, it’s really self-explanatory. I used to work as a trouble-shooter, so climbing into code quickly was basically my job. The fact of the matter, there’s no substitute for good documentation, none! On a side note: my IDE’s auto-completion window comes up with the field or methods documentation. Sure the code is a CTRL-Click away, but that’s an extra step, and another trawl through other code that I really don’t need.
Personally I love writing documentation explaining how my code works, where it has flaws and where it’s really cool. One annotation I wrote yesterday is a marker annotation (ie: it’s got no attributes), I wrote over 30 lines of documentation for it. It probably sounds like overkill to most people, but trust me on this, without it, people would have to spend a whole lot of extra time figuring out what my code does.
The message here is: don’t forget to document your code!
