My buddy Mike writes in his Blog about how he's glad he documented all his code for his work project.

Eagleson's Law

Any code of your own that you haven?t looked at for six or more months, might as well have been written by someone else. (Eagleson is an optimist, the real number is more like three weeks.)

[...]

If I hadn?t liberally commented all my source code I would be in a heap of trouble.

JavaDoc is one of the best things to ever happen to programming.

The concept of JavaDoc is that you have to write a comment before every class of object explaining what it does, and a comment before every function explaining what information it needs, what it does, and what information it returns.

Consider the following JavaDoc-ed code:

I think JavaDoc makes code clear enough that even non-programmers can understand it. What makes JavaDoc so great is that it's systematic. Since you need to include all those bullet points (@), you never forget to document anything. If you were just to document your code whenever you felt like it, you'd never document, 'cause you'd never feel like it. And then you forget what the code does. And then you have to read the code, and think for a while. All a big waste of time.

When I started my job, they gave me a huge codebase, and told me to get cracking. I didn't know how anything worked at all. So how did I manage to jump in so fast? I just started writing JavaDocs on every method I encountered ('cause the guy who first wrote it didn't write any JavaDocs! Grr!) I'd read the code, try to figure out what it did, and then wrote a JavaDoc explaining what it did. Sometimes I'd get it wrong, so I'd have to rewrite the JavaDoc, but most of the time I got it right. And very quickly, I had a fully documented system (or at least, the parts I was involved with were documented).

Once the entire system was documented, it became very easy to work with, and I could start actually contributing productive code. And the time I spent figuring out how everything works - it wasn't wasted, because now the system is documented, so when the next guy comes along, he won't have to spend the time I did figuring everything out.

My advice to all would be programmers out there, write your code as if it were open source; i.e. in such a way so that you won't be ashamed to show it to one of your peers. Because one day you're going to be that "peer" who has to look at that code again, and if it's godawful ugly code, you're not going to enjoy working with it.