Mar 2, 2012

How to write javadoc tips

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:
  •  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)
Last, a bit vague advice -  do not repeat class/method name. Describe code in business terms, using different words than in code. If you can-not do it or method is pretty obvious - don't write it.

1 comment:

Artyom Abalmasov said...

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