Code Documentation

[Teq]

I've just been working on part of one of my applications during my lunch hour (nice to take a break for web application development and do some stand-alone work) , in the middle of which the thought occurred to me that I might want to be documenting some of the methods I'm writing - as I'm working on Java, JDocumentor seems like the way to go, after all, the only people reading this will be developers, was just wondering what your thoughts on the subject are, document through code comments, or document in standard English (or any other method)?

[spellcaster]

You'll need both.

You'll need one documentation outlining the modules of your product. Explaining what each module does and where connctions are.

Why is this important? Say you have a bunch of java classes. Now you'll have to start somewhere - just browing the JDoc generated code tree won't help you here.

Also, you might split your product into several projects (client / server / base lib, etc) and want to document how these elements are working together.

And finally, remember that the "why and how" is always more important then the "what". So, something like:

// doubles foo to make sure it works
foo *= 2;

isn't worth a comment. Also, from my experience it's better to document code parts ("Iterate the event list to see if an URGENT event has occured") instead of documenting the individual steps.

Also, the more meta information you embed, the more easy it is for you to become familiar with the code again.


Oh, and finally - try to write clean code, use self documenting variable and function names, and you won't need to document as extensivly.

[Teq]

Definately want to avoid using variable names like foo ;) Definately agree with you, I do a lot of development in differing languages and it is sometimes pretty time consuming trying to work out what I've been attempting to achieve.