July 7, 2012 by huionn
From my experience, Design By Contract is one of the key for maintainable codes. JavaDoc is useful for description, but too verbose in practice. Although Design By Contract is not natively supported by Java, its intention can be achieved through Java Annotation.
There is JSR 305: Annotations for Software Defect Detection (http://jcp.org/en/jsr/detail?id=305), unfortunately it is not getting much traction and is in dormant status now.
For simplicity, so I come out myself a few of annotations that are useful for self-documented codes:
- MayBeModified: the provided parameter may be modified in the method
- Asynchronous: a method (for a process requiring long time to complete) which return immediately in non-blocking manner
- Blocking: a synchronous method which blocks until the processing complete