General Rules
- Language: ENGLISH
- avoid non-ASCII characters or use UTF-8 encoding (in cases such as a German resource bundle)
High-Level (Description of architecture)
A couple of paragraphs that provide an initial overview and answer the following questions:
- What is the program doing? Which functions are provided?
- What is it not doing (yet)? List of work left to be done in the future.
- Which parts/modules/packages does the program have? (Focus on larger building blocks of the entire system rather than details on single classes.) What are they doing?
- Graphical overview as UML diagram.
- What are the inputs? In which format?
- What are the outputs? In which format?
- What is stored in which way? (Data model as diagram + description)
Low-Level (Source Code, Javadoc)
Variable and method names are either full words (or composites of full words) or the unabbreviated variant is provided along with its declaration. A large amount of the low-level documentation should be provided using Javadoc. In case two things are referring to each other, redundant descriptions on both places can be omitted if they are not further than 10-20 lines apart (depending on the complexity).
Javadoc
For each class
- 1 line short description
- Purpose of the class? What does it model?
- What is it doing? (No listing of methods but a high level description of its functionality including most important methods and variables.)
- What other classes does it use? Why? (Except java.lang.*)
For each method (including private ones)
- 1 line short description
- What is it doing?
- What class variables are used? How? Why?
- Arguments/parameters and return value: short description + description about usage
For each class variable (including private ones)
- 1 line short description. What does it store?
- Who is setting it, who is reading it?
- Value range
- Explanation of values (if necessary)
Additionally
- in case of complex algorithms
- when using dirty tricks
- in case of exotic system calls
- for describing local variables, especially when they have very short names and their usage is non-trivial
- in any other case where things are not quite clear
An API documentation needs to be created using Javadoc and put into the /javadoc directory (see Structure & Content of Documents to Submit)