[jboss-dev] Developer javadoc is essential!
Jason T. Greene
jason.greene at redhat.com
Thu May 28 16:41:31 EDT 2009
Hi Guys,
The javadoc/code comments in our core modules are VERY lacking, so it is
incredibly difficult for new folks to understand how anything is
supposed to work (I have been hearing some groaning about this recently).
All of our code, especially SPI or API classes must have javadoc which
explains in detail the following things:
1) How the module is supposed to be used (and how it is actually used if
known)
2) The intended behavior, and any aspect of it that is known to be
broken or a hack (so that someone can differentiate between a design
problem and just an unimplemented section that needs to be fixed)
3) Crticial preconditions (e.g. "this class expects that the same vfs
handle instance be reused during a redeploy")
4) Thread-access design (e.g. "this class is thread-safe and can be
accessed from multiple threads", "this class is not thread-safe, and all
callers must use a shared lock to access", "this class is intended to
have an instance-per-thread")
If we can't answer these simple questions, then it is likely our design
is flawed.
--
Jason T. Greene
JBoss, a division of Red Hat
More information about the jboss-development
mailing list