Here is where I'll put the guidelines for documenting code before checking-in.
These are mostly just thoughts, with some support from Code Complete.
- Don't explain the code, explain the intent - This I have a lot of trouble with, and have to force myself to do (I'm getting better, but still not great). We can read the code and understand it, we can't read the code and understand the intent. Therefore, documenting what the code is intended to do and not document how it does it helps fill in holes in understanding, and holds up better as the code changes. This rule will get broken when documenting simple methods for Javadoc, but keep this rule in mind when documenting complex methods and class descriptions.
- Document before you write - When writing a new class document as pseudo-code (a very high level pseudo-code). This is a hard habit to get into, but something I've found useful when I can force myself to do it.
- Fix/Documenting code you are working on - As soon as you need to touch any code, read the existing comments and confirm they are accurate. Fill in any missing documentation. Then start your work. As you work, document. Some classes are very large, and this become a bit of a pain, but most are quite manageable.
- Before committing to CVS documentation must be complete - before anything is allowed to be committed into CVS, it now must be well documented.
- Document bug fixes, oddities with your initials - If you fixed a bug, or do something unconventional add a small comment with your initials afterwards.
This is just the start, and I'm getting pressure to finish getting ready so we can start our vacation (I'll be gone for a week with no net access). I've been trying to apply this at work (but haven't been working on jME code, so haven't had a lot to contribute back). But even so, I realize how hard it is to follow these rules (I still crank out quick data classes with no docs). But, my feeling is, the longer I strive to follow some rules, the easier it becomes.
There are also a few more rules that I wanted to point out that I'd like to add, but can't remember right now, so I'll get back to this thread in a week.
IMO, the most important aspect is to document the intent before the code. Then once the intent is established, follow up with the standard filler comments to make the Javadoc complete.
Feel free to disagree, I won't be here to see it! I'll consolidate all comments back into this post when I get back next week.