I remember about seven years ago, when I was learning Java, I thought Javadoc was cool, and that it would take care of a lot of the documentation problems that I've felt frustrated with for years...

Developers hate writing documentation, I fairly sparsely comment my own code, preferring to make the code logical to read, and only commenting those bits that need a "heads-up" from a fellow coder. The problem with Javadoc is that it only documents APIs, it's hard to document intent.

I was reading through the an old codebase for a project I worked on around 5 years ago, and it was amusing reading the documentation for it, there was a lot o API style documentation, which is reasonably useful, but there was also a lot of orientation documentation.

I read the documentation with interest, not having read it for close to four years, it was written as both a guide to the vision that we were following, and as a practical "look here if you want to know this" guide.

Amazingly, nobody other than the original developers, had ever had to be "inducted" into to the code, all the original developers were still there.

The moral of this tale? Coders can read code, it's much harder to read the intention from the code, so don't rely on Javadoc or any of the automatic documentation generators.

- posted by bigkevmcd @ 5:57 AM