Code and Test Documentation

Michal gave a presentation on "Documentation" and at some point Abdul was asking what to put for "code documentation" and I had a similar question in mind for "Test Documentation."

I found this document for "Software Documentation" which gives a general idea what to put for "code and test" documentation.

Code Documentation (CD)
You are expected to fully document your code. Every class and class method should have a name, a brief one-line description, and a detailed description of the algorithm. All methods also require descriptions of all inputs and outputs. If applicable, you should also note any caveats – things that could go wrong or things that the code doesn’t address. Put assumptions in the caveats section. If you are coding in Java, you should use the documentation tags that work with the javadoc utility. This utility automatically generates web pages for your documentation. To make things consistent, simply cut and paste the textual descriptions of your classes, objects, and methods from your OOD directly into the code. Then let javadoc do the dirty work. If you are not coding in Java, you can still use the same tags and see if javadoc operates on your source files. Otherwise, you could write such a utility yourself!

Testing Documentation (TD)
The TD describes how you tested your program to prove that it works sucessfully. You should include testbeds for both the user interface and application aspects of your program. You should also provide test data sets where applicable. For example, if you program does some form of text processing, you should provide example file inputs that test specific features of the program requirements. You should pay special attention to borderline values and bogus user input. The TD should also include evaluation criteria, so you know what you are actually testing for.


http://www.assembla.com/spaces/atmr/documents/aZ9_Eul38r3PpneJe5afGb/download/software_documentation.pdf