Re: [jboss-dev] Developer javadoc is essential!

Jason, yes, I very much agree. This has been brought under way for MC = please monitor https://jira.jboss.org/jira/browse/JBMICROCONT-442 To enforce "must have javadoc" I created https://jira.jboss.org/jira/browse/JBAS-6994 Perhaps you like to ping the individual leads to create/name their respective JIRA issues that are supposed to improve the situation in their camp and have those linked to the one above. cheers -thomas Jason T. Greene wrote: > 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. -- xxxxxxxxxxxxxxxxxxxxxxxxxxxx Thomas Diesler JBoss, a division of Red Hat 2009 Red Hat Summit and JBoss World. Chicago. September 1-4, 2009. http://www.redhat.com/summit http://www.jbossworld.com xxxxxxxxxxxxxxxxxxxxxxxxxxxx _______________________________________________ jboss-development mailing list jboss-development(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/jboss-development