Worst documentation for code is one that repeats code. Some companies want to avoid this pitfall by implementing "no javadoc" rule (I'm talking about java). This is wrong.
Using following tips (hopefully) will help you to produce meaningful documentation for code:
Using following tips (hopefully) will help you to produce meaningful documentation for code:
- Use questions in templates for documentation. It's more mind stimulating to answer "What does this class do ?" than replace template "Write description of the class"
- Write CRC in documentation. CRC means class-responsibility-collaborator data. Example:
- class: What is it ?
- responsibility: What and when does it work, what valuable does it do ?
- collaborator: What classes/modules uses this class ? What classes/modules is used by it ?
- Example of use. Basic usage scenario in javadoc is most useful thing. It's got noticed on first place (almost every class in JDK has one).
- Design By Contract: For both class and method it's important to know:
- Precondition:
- When it's legal to use class/method?
- What is a valid types and boundary conditions for arguments? Null, string format, data range
- What is true about method/class execution (thread safe, can produce exception, require external resources, linked with other methods/classes)
- What is possible outcome ? (Empty array, value object)
1 comment:
Ooops, I completely forgot my previous post about same theme.
It's slightly larger.
http://blog.abalmasov.com/2007/10/how-to-write-javadoc.html
Post a Comment