Documenting Task

1

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.


  1. 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.


  2. 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.


  3. 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.


  4. Before committing to CVS documentation must be complete - before anything is allowed to be committed into CVS, it now must be well documented.


  5. 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! :slight_smile: I'll consolidate all comments back into this post when I get back next week.
2

Sounds good/normal.



Only note: adding initials is usually not necessary, as cvs annotate usually reveals the author of a line anyway.

3

Hm there's always the chance we'll loose the CVS history (like say, when we switch to SVN after 1.0 is released?)

4

Converting to svn is possible with preserving version history. I'd even say we should convert only if that's the case.

5

I wouldn't say we should ONLY convert if that's the case, but it shouldn't be difficult to do.

6

One thing that we need for documentation (very apparent after getting caught up on posts) is User's Guide.



Because I am not currently working on jME code, I rarely access it to improve the javadoc.



What I am going to do is start working on the User's Guide in the wiki, and try to get that up to spec (as much as my tech. writing skills will allow). I'll take that burden on.



That's not to say I won't Javadoc when working on jme classes. :wink:

7

Cool, having a fully featured User Guide will be huge for us.

8

a great thing!